groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M2T3S1/research/PRD_LOCATION_ANALYSIS.md

@@ -0,0 +1,199 @@
+# PRD Location Analysis for @Step Decorator Options
+
+## Executive Summary
+
+This document provides the exact location of the @Step Decorator Options documentation in the PRD and identifies where the trackTiming default value needs to be documented.
+
+## Primary PRD Location
+
+**File**: `/home/dustin/projects/groundswell/PRD.md`
+**Section**: 8.1 @Step() Decorator
+**Lines**: 177-189
+
+### Current PRD Content (Lines 177-189)
+
+```typescript
+## **8.1 @Step() Decorator**
+
+```ts
+export interface StepOptions {
+  name?: string;
+  snapshotState?: boolean;
+  trackTiming?: boolean;
+  logStart?: boolean;
+  logFinish?: boolean;
+}
+
+export function Step(options: StepOptions = {}): MethodDecorator;
+```
+
+**Responsibilities:**
+
+* Emit `stepStart` + `stepEnd`.
+* Optionally snapshot state.
+* Catch and wrap errors into `WorkflowError`.
+```
+
+## Issue Identified
+
+The PRD Section 8.1 defines the `trackTiming?: boolean` option but **does not explicitly state the default value**.
+
+### Implementation Reality
+
+The implementation clearly shows the default is `true`:
+
+**File**: `src/decorators/step.ts`
+**Line**: 94
+
+```typescript
+if (opts.trackTiming !== false) {
+  wf.emitEvent({
+    type: 'stepEnd',
+    node: wf.node,
+    step: stepName,
+    duration,
+  });
+}
+```
+
+The condition `opts.trackTiming !== false` means:
+- Default behavior: timing IS tracked (unless explicitly disabled)
+- To disable: user must set `trackTiming: false`
+
+### Type Definition Clarity
+
+**File**: `src/types/decorators.ts`
+**Lines**: 11-12
+
+```typescript
+/** Track and emit step duration (default: true) */
+trackTiming?: boolean;
+```
+
+The TypeScript type definition DOES include the default value in JSDoc comment, but the PRD does not.
+
+## Other Documentation Locations
+
+### README.md (User-Facing Documentation)
+
+**File**: `/home/dustin/projects/groundswell/README.md`
+**Lines**: 129-136
+
+```markdown
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | method name | Custom step name |
+| `trackTiming` | `boolean` | `true` | Include duration in `stepEnd` event. Set to `false` to eliminate timing overhead. |
+| `snapshotState` | `boolean` | `false` | Capture state snapshot after step completion |
+| `logStart` | `boolean` | `false` | Log message at step start |
+| `logFinish` | `boolean` | `false` | Log message at step end (includes duration) |
+```
+
+The README **correctly documents** the default value as `true` with a clear explanation.
+
+## Documentation Gap Analysis
+
+| Location | Has Default Value | Format | Status |
+|----------|------------------|--------|--------|
+| PRD.md (Section 8.1) | ❌ No | TypeScript interface | Needs update |
+| src/types/decorators.ts | ✅ Yes | JSDoc comment | Correct |
+| src/decorators/step.ts | ✅ Yes | Code logic | Correct |
+| README.md | ✅ Yes | Table format | Correct |
+
+## Recommended PRD Update
+
+### Option 1: Add inline comment in interface
+
+```typescript
+export interface StepOptions {
+  name?: string;                          // defaults to method name
+  snapshotState?: boolean;                // defaults to false
+  trackTiming?: boolean;                  // defaults to true
+  logStart?: boolean;                     // defaults to false
+  logFinish?: boolean;                    // defaults to false
+}
+```
+
+### Option 2: Add description table (Recommended)
+
+Add a table after the interface definition:
+
+```typescript
+export interface StepOptions {
+  name?: string;
+  snapshotState?: boolean;
+  trackTiming?: boolean;
+  logStart?: boolean;
+  logFinish?: boolean;
+}
+
+// Default values:
+// | Option | Default | Description |
+// |--------|---------|-------------|
+// | name | method name | Custom step name |
+// | snapshotState | false | Capture state snapshot after step completion |
+// | trackTiming | true | Track and emit step duration |
+// | logStart | false | Log message at step start |
+// | logFinish | false | Log message at step end |
+```
+
+### Option 3: Add JSDoc-style documentation (Most Complete)
+
+```typescript
+/**
+ * @Step Decorator Options
+ *
+ * @option name - Custom step name (default: method name)
+ * @option snapshotState - Capture state snapshot after step completion (default: false)
+ * @option trackTiming - Track and emit step duration in stepEnd event (default: true)
+ * @option logStart - Log message at step start (default: false)
+ * @option logFinish - Log message at step end including duration (default: false)
+ */
+export interface StepOptions {
+  name?: string;
+  snapshotState?: boolean;
+  trackTiming?: boolean;
+  logStart?: boolean;
+  logFinish?: boolean;
+}
+```
+
+## Related Files
+
+1. **Main PRD**: `/home/dustin/projects/groundswell/PRD.md` (lines 177-189)
+2. **Type Definition**: `/home/dustin/projects/groundswell/src/types/decorators.ts` (lines 6-17)
+3. **Implementation**: `/home/dustin/projects/groundswell/src/decorators/step.ts` (lines 17-101)
+4. **User Documentation**: `/home/dustin/projects/groundswell/README.md` (lines 129-136)
+5. **Examples**: `/home/dustin/projects/groundswell/examples/examples/02-decorator-options.ts`
+
+## Conclusion
+
+The exact file path and line number for the @Step decorator options documentation is:
+- **File**: `/home/dustin/projects/groundswell/PRD.md`
+- **Section**: 8.1 @Step() Decorator
+- **Lines**: 177-189
+- **Specific Line for trackTiming**: Line 183
+
+The PRD needs to be updated to explicitly state that `trackTiming` defaults to `true`, matching the implementation and user-facing documentation.
+
+---
+
+## Handoff to P1.M2.T3.S2
+
+**Next Task**: Update PRD.md line 183 to add default value documentation
+
+**Recommended Update** (simple inline comment for PRD consistency):
+```typescript
+trackTiming?: boolean;  // default: true
+```
+
+**Verification Command** (run after S2 completes):
+```bash
+grep -A2 -B2 "trackTiming" PRD.md
+```
+
+---
+
+**Research Task**: P1.M2.T3.S1 - Locate PRD Section for @Step Decorator Options
+**Research Date**: 2026-01-12
+**Next Task**: P1.M2.T3.S2 - Update PRD with trackTiming default value

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M2T3S1/research/ULTRATHINK_PRP_PLAN.md

@@ -0,0 +1,134 @@
+# ULTRATHINK Plan: P1.M2.T3.S1 PRP Structure
+
+## PRP Purpose
+Create a Product Requirement Prompt for the research task: "Locate PRD section for @Step decorator options"
+
+## Key Insight
+This is a **PURE RESEARCH task** - no code changes, only documentation location and analysis.
+
+## Template Section Planning
+
+### Goal Section
+- **Feature Goal**: Locate and document the exact location of PRD Section 8.1 (@Step Decorator Options) and the trackTiming option
+- **Deliverable**: Research report with exact file path, line numbers, and documentation gap analysis
+- **Success Definition**: Exact location identified, trackTiming default value status confirmed, documentation gap documented
+
+### User Persona
+- **Target User**: Documentation maintainer / Developer needing to update PRD
+- **Use Case**: Need to find where in the PRD to add the trackTiming default value documentation
+- **Pain Points**: PRD is large, default value is not explicitly documented, implementation shows default=true but PRD doesn't state it
+
+### Why Section
+- Documentation gap causes confusion about default behavior
+- Implementation uses `!== false` pattern (defaults to true) but PRD doesn't specify
+- Next subtask (P1.M2.T3.S2) needs this location to update the PRD
+
+### What Section
+- User-visible: Research findings with file paths and line numbers
+- Success Criteria:
+  - [ ] Exact file path for PRD Section 8.1 identified
+  - [ ] Line number for trackTiming documented
+  - [ ] Documentation gap confirmed
+  - [ ] Research files stored
+
+### All Needed Context
+#### Documentation & References
+```yaml
+# MUST READ - Key files for PRD location
+- file: PRD.md
+  lines: 177-189
+  why: Contains Section 8.1 @Step Decorator Options definition
+  pattern: TypeScript interface StepOptions with trackTiming?: boolean
+  gotcha: Default value NOT documented in PRD, only in type definitions
+
+- file: src/types/decorators.ts
+  lines: 6-17
+  why: Contains JSDoc comment showing "Track and emit step duration (default: true)"
+  pattern: JSDoc comments above interface properties
+  gotcha: PRD doesn't match this JSDoc documentation
+
+- file: src/decorators/step.ts
+  lines: 94-101
+  why: Contains implementation showing default behavior: if (opts.trackTiming !== false)
+  pattern: Negation pattern means default is true
+  gotcha: Default behavior is opt-out, not opt-in
+
+- file: README.md
+  lines: 129-136
+  why: User-facing table correctly shows trackTiming default: true
+  pattern: Markdown table with Default column
+  gotcha: User docs are correct, PRD is incomplete
+
+- docfile: plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M2T3S1/research/PRD_LOCATION_ANALYSIS.md
+  why: Detailed analysis of PRD location and documentation gap
+  section: Conclusion
+
+- docfile: plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M2T3S1/research/DECORATOR_DOCUMENTATION_PATTERNS.md
+  why: External research on documentation best practices
+  section: Recommended Patterns for Groundswell PRD
+
+- docfile: plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M2T3S1/research/CODEBASE_INVENTORY.md
+  why: Complete inventory of all trackTiming references
+  section: Summary Table
+```
+
+### Implementation Blueprint
+Since this is a research task:
+- No data models needed
+- No implementation tasks needed
+- Only research and documentation activities
+
+### Implementation Tasks (Research-Focused)
+```yaml
+Task 1: LOCATE PRD Section 8.1
+  - FIND: File path /home/dustin/projects/groundswell/PRD.md
+  - READ: Lines 177-189 for @Step Decorator Options
+  - IDENTIFY: Line 183 containing trackTiming?: boolean
+  - CONFIRM: Default value is NOT documented in PRD
+
+Task 2: VERIFY Implementation Default
+  - READ: src/decorators/step.ts line 94
+  - ANALYZE: if (opts.trackTiming !== false) pattern
+  - CONFIRM: Default is true (opt-out, not opt-in)
+
+Task 3: COMPARE Documentation Sources
+  - CHECK: src/types/decorators.ts JSDoc comment
+  - CHECK: README.md table documentation
+  - CONFIRM: Type defs and README correctly show default: true
+  - IDENTIFY: PRD is the only source missing this information
+
+Task 4: CREATE Research Report
+  - WRITE: Research findings to research/ subdirectory
+  - DOCUMENT: Exact file paths, line numbers, documentation gap
+  - PROVIDE: Recommendations for PRD update (for S2)
+```
+
+### Validation Loop (Research-Specific)
+```bash
+# Level 1: Research Completeness
+ls plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M2T3S1/research/
+# Expected: 3 research files created
+
+# Level 2: Location Verification
+grep -n "trackTiming" PRD.md
+# Expected: Line 183 shows trackTiming?: boolean
+
+# Level 3: Documentation Gap Confirmation
+grep -A2 -B2 "trackTiming" PRD.md | grep -i "default"
+# Expected: No results (confirms gap exists)
+
+# Level 4: Implementation Verification
+grep "trackTiming !== false" src/decorators/step.ts
+# Expected: Line 94 confirms default is true
+```
+
+### Final Validation Checklist
+- [ ] PRD Section 8.1 location documented: PRD.md lines 177-189
+- [ ] trackTiming line number documented: Line 183
+- [ ] Documentation gap confirmed (no default value in PRD)
+- [ ] Implementation default verified: true (via !== false pattern)
+- [ ] Research files stored in P1M2T3S1/research/
+- [ ] Next task (S2) has clear location for PRD update
+
+## Confidence Score
+**10/10** - This is straightforward research with clear deliverables and existing documentation to verify against.