groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/docs/research/P1M2T1S4/DECORATOR_DOCUMENTATION_BEST_PRACTICES.md

@@ -1,716 +0,0 @@
-# TypeScript Decorator Documentation Best Practices
-
-**Research Date:** 2026-01-11
-**Researcher:** Claude Code Agent
-**Purpose:** Comprehensive research on best practices for documenting TypeScript decorator options in README.md files
-
----
-
-## Table of Contents
-
-1. [Executive Summary](#executive-summary)
-2. [Key Findings](#key-findings)
-3. [Documentation Structure Patterns](#documentation-structure-patterns)
-4. [Showing Default Values](#showing-default-values)
-5. [Table Formatting Best Practices](#table-formatting-best-practices)
-6. [Code Example Patterns](#code-example-patterns)
-7. [Real-World Examples](#real-world-examples)
-8. [Recommended Template](#recommended-template)
-9. [URLs and References](#urls-and-references)
-
----
-
-## Executive Summary
-
-After analyzing popular TypeScript decorator libraries and the Groundswell codebase, I've identified the most effective patterns for documenting decorator options. The research reveals that **clear tables with default values, progressive code examples, and explicit type information** are the hallmarks of excellent decorator documentation.
-
-**Key Insight:** Users need to understand three things immediately:
-1. What options exist (comprehensive list)
-2. What the defaults are (reduces cognitive load)
-3. How to use them in practice (code examples)
-
----
-
-## Key Findings
-
-### Current State in Groundswell
-
-The current documentation in `/home/dustin/projects/groundswell/docs/workflow.md` uses tables effectively:
-
-```markdown
-**Options:**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `name` | `string` | Custom step name (defaults to method name) |
-| `snapshotState` | `boolean` | Capture state snapshot after step completion |
-| `trackTiming` | `boolean` | Track and emit step duration |
-```
-
-**Missing Elements:**
-- No explicit "Default" column
-- Defaults hidden in descriptions
-- No visual distinction between optional and required
-- No progressive examples showing default vs overridden behavior
-
-### Best Practices Identified
-
-1. **Add a Default Column** - Separate defaults from descriptions
-2. **Show Progressive Examples** - Start with defaults, then show overrides
-3. **Use Inline Comments** - Document behavior at the point of use
-4. **Group Related Options** - Logical organization aids discoverability
-5. **Link to Type Definitions** - Enable deep dives for advanced users
-
----
-
-## Documentation Structure Patterns
-
-### Pattern 1: The "Progressive Disclosure" Approach (Recommended)
-
-Structure documentation from simplest to most complex:
-
-```markdown
-## @Step Decorator
-
-Wraps methods with event emission and error handling.
-
-### Basic Usage (All Defaults)
-
-```typescript
-class MyWorkflow extends Workflow {
-  @Step()  // Uses all defaults
-  async processData(): Promise<void> {}
-}
-```
-
-### With Options
-
-```typescript
-class MyWorkflow extends Workflow {
-  @Step({ trackTiming: true })
-  async timedStep(): Promise<void> {}
-}
-```
-
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `name` | `string` | method name | Custom step name |
-| `trackTiming` | `boolean` | `true` | Track execution duration |
-| `snapshotState` | `boolean` | `false` | Capture state after completion |
-```
-
-**Why This Works:**
-- Beginners see simple usage first
-- Advanced users can jump to the reference table
-- Defaults are explicit, not hidden in prose
-
-### Pattern 2: The "Reference First" Approach
-
-Start with the complete table, then show examples:
-
-```markdown
-## @Step Decorator
-
-### Configuration Options
-
-[Complete table here]
-
-### Examples
-
-[Bullet points with code snippets]
-```
-
-**Use When:**
-- Documentation is for reference only
-- Users are already familiar with basics
-- API stability is high
-
-### Pattern 3: The "Example-Driven" Approach
-
-Lead with examples, follow with reference:
-
-```markdown
-## @Step Decorator
-
-### Common Patterns
-
-**Basic Step:**
-```typescript
-@Step()
-async myMethod() {}
-```
-
-**Named Step:**
-```typescript
-@Step({ name: 'CustomName' })
-async myMethod() {}
-```
-
-**All Options:**
-```typescript
-@Step({
-  name: 'CustomName',
-  trackTiming: true,
-  snapshotState: true
-})
-async myMethod() {}
-```
-
-### API Reference
-
-[Complete table]
-```
-
-**Use When:**
-- Onboarding new users
-- Decorator has many options
-- Visual learners are target audience
-
----
-
-## Showing Default Values
-
-### Method 1: Dedicated Default Column (Best Practice)
-
-```markdown
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `trackTiming` | `boolean` | `true` | Track execution duration |
-| `logStart` | `boolean` | `false` | Log at method start |
-| `logFinish` | `boolean` | `false` | Log at method end |
-```
-
-**Advantages:**
-- Defaults are immediately visible
-- Easy to scan
-- Reduces cognitive load
-- Enables quick comparisons
-
-### Method 2: Inline in Description (Current Groundswell Pattern)
-
-```markdown
-| Option | Type | Description |
-|--------|------|-------------|
-| `trackTiming` | `boolean` | Track execution duration (default: true) |
-| `logStart` | `boolean` | Log at method start (default: false) |
-```
-
-**Advantages:**
-- Simpler table structure
-- Works for complex defaults
-- Easier to maintain
-
-**Disadvantages:**
-- Harder to scan
-- Inconsistent formatting
-- Defaults not immediately visible
-
-### Method 3: Code-Based Defaults
-
-```markdown
-| Option | Type | Default |
-|--------|------|---------|
-| `trackTiming` | `boolean` | `true` |
-| `logStart` | `boolean` | `false` |
-
-**Descriptions:**
-- `trackTiming`: Track execution duration
-- `logStart`: Log at method start
-```
-
-**Advantages:**
-- Very clean table
-- Descriptions can be longer
-
-**Disadvantages:**
-- Requires more vertical space
-- Harder to correlate option with description
-
-### Recommendation: Use Method 1
-
-The dedicated "Default" column provides the best user experience for documentation scanning.
-
----
-
-## Table Formatting Best Practices
-
-### 1. Column Order (Standard Pattern)
-
-```markdown
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-```
-
-**Rationale:**
-1. **Option** - What you configure
-2. **Type** - What values are valid
-3. **Default** - What happens if you don't set it
-4. **Description** - What it actually does
-
-### 2. Code Formatting in Tables
-
-Use inline code for all identifiers:
-
-```markdown
-| Option | Type | Default |
-|--------|------|---------|
-| `name` | `string` | method name |
-| `trackTiming` | `boolean` | `true` |
-```
-
-### 3. Handling Complex Defaults
-
-For non-trivial defaults, be explicit:
-
-```markdown
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `validator` | `ValidatorFn` | `undefined` | Custom validation function |
-| `retryPolicy` | `RetryPolicy` | `{ maxAttempts: 3, backoff: 'exponential' }` | Retry configuration |
-```
-
-### 4. Grouping Related Options
-
-Use subheadings or visual separators:
-
-```markdown
-#### Logging Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `logStart` | `boolean` | `false` | Log at start |
-| `logFinish` | `boolean` | `false` | Log at completion |
-
-#### Performance Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `trackTiming` | `boolean` | `true` | Track duration |
-| `cacheResult` | `boolean` | `false` | Cache return value |
-```
-
----
-
-## Code Example Patterns
-
-### Pattern 1: Progressive Complexity
-
-Show default behavior first, then add options:
-
-```typescript
-// Level 1: Default behavior
-@Step()
-async basicMethod(): Promise<void> {}
-
-// Level 2: Single option
-@Step({ trackTiming: true })
-async timedMethod(): Promise<void> {}
-
-// Level 3: Multiple options
-@Step({
-  name: 'CustomStep',
-  trackTiming: true,
-  snapshotState: true
-})
-async configuredMethod(): Promise<void> {}
-```
-
-### Pattern 2: Inline Option Documentation
-
-Use comments to explain each option:
-
-```typescript
-@Step({
-  name: 'DataProcessing',      // Custom name for logs/events
-  trackTiming: true,            // Emits stepEnd event with duration
-  snapshotState: true,          // Captures @ObservedState fields
-  logStart: true,               // Logs "Starting step: DataProcessing"
-  logFinish: true,              // Logs "Completed step: DataProcessing"
-})
-async processData(): Promise<void> {
-  // ... implementation
-}
-```
-
-### Pattern 3: Side-by-Side Comparison
-
-Show behavior with and without options:
-
-```typescript
-// Without snapshotState - state not captured
-@Step()
-async step1(): Promise<void> {
-  this.progress = 50;  // Lost after method completes
-}
-
-// With snapshotState - state preserved
-@Step({ snapshotState: true })
-async step2(): Promise<void> {
-  this.progress = 100;  // Captured in stateSnapshot event
-}
-```
-
----
-
-## Real-World Examples
-
-### Example 1: Current Groundswell Documentation
-
-**File:** `/home/dustin/projects/groundswell/docs/workflow.md`
-
-**Current Structure:**
-```markdown
-### @Step
-
-Wraps methods with event emission and error handling.
-
-```typescript
-import { Step } from 'groundswell';
-
-class MyWorkflow extends Workflow {
-  // Default - emits stepStart/stepEnd events
-  @Step()
-  async basicStep(): Promise<void> {}
-
-  // Custom name
-  @Step({ name: 'CustomStepName' })
-  async namedStep(): Promise<void> {}
-
-  // Capture state after completion
-  @Step({ snapshotState: true })
-  async snapshotStep(): Promise<void> {}
-
-  // Track execution duration
-  @Step({ trackTiming: true })
-  async timedStep(): Promise<void> {}
-
-  // Log start/end messages
-  @Step({ logStart: true, logFinish: true })
-  async loggedStep(): Promise<void> {}
-
-  // All options
-  @Step({
-    name: 'FullStep',
-    snapshotState: true,
-    trackTiming: true,
-    logStart: true,
-    logFinish: true,
-  })
-  async fullStep(): Promise<void> {}
-}
-```
-
-**Options:**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `name` | `string` | Custom step name (defaults to method name) |
-| `snapshotState` | `boolean` | Capture state snapshot after step completion |
-| `trackTiming` | `boolean` | Track and emit step duration |
-| `logStart` | `boolean` | Log message when step starts |
-| `logFinish` | `boolean` | Log message when step completes |
-```
-
-**Strengths:**
-- Excellent progressive examples
-- Clear code formatting
-- Shows all options in use
-
-**Weaknesses:**
-- No dedicated Default column
-- Defaults hidden in parentheses
-- No visual distinction for required vs optional
-
-**Recommended Improvement:**
-
-```markdown
-**Options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `name` | `string` | method name | Custom step name for logs/events |
-| `snapshotState` | `boolean` | `false` | Capture state snapshot after completion |
-| `trackTiming` | `boolean` | `true` | Track and emit step duration |
-| `logStart` | `boolean` | `false` | Log message when step starts |
-| `logFinish` | `boolean` | `false` | Log message when step completes |
-```
-
-### Example 2: Groundswell README
-
-**File:** `/home/dustin/projects/groundswell/README.md`
-
-**Current Approach:**
-```typescript
-// Emit lifecycle events and track timing
-@Step({ trackTiming: true, snapshotState: true })
-async processData(): Promise<void> { }
-
-// Spawn and manage child workflows
-@Task({ concurrent: true })
-async createWorkers(): Promise<WorkerWorkflow[]> { }
-
-// Mark fields for state snapshots
-@ObservedState()
-progress: number = 0;
-
-@ObservedState({ redact: true })  // Shown as '***'
-apiKey: string = 'secret';
-```
-
-**Strengths:**
-- Inline comments explain behavior
-- Shows common patterns concisely
-- Uses code examples as documentation
-
-**Weaknesses:**
-- Not comprehensive (quick start only)
-- No table reference
-- Defaults not shown
-
-**Best Use Case:** Quick start / overview sections
-
-### Example 3: Type Definitions
-
-**File:** `/home/dustin/projects/groundswell/src/types/decorators.ts`
-
-```typescript
-/**
- * Configuration options for @Step decorator
- */
-export interface StepOptions {
-  /** Custom step name (defaults to method name) */
-  name?: string;
-  /** If true, capture state snapshot after step completion */
-  snapshotState?: boolean;
-  /** Track and emit step duration (default: true) */
-  trackTiming?: boolean;
-  /** If true, log message at step start */
-  logStart?: boolean;
-  /** If true, log message at step end */
-  logFinish?: boolean;
-}
-```
-
-**Strengths:**
-- JSDoc comments provide inline documentation
-- Types visible in IDE
-- Defaults mentioned in comments
-
-**Weaknesses:**
-- Not user-facing (requires reading source)
-- Defaults inconsistent (sometimes mentioned, sometimes not)
-- No examples
-
-**Best Practice:** Keep JSDoc in sync with README documentation
-
----
-
-## Recommended Template
-
-### Template for Decorator Documentation
-
-```markdown
-## @DecoratorName
-
-**Brief one-line description of what the decorator does.**
-
-### Basic Usage
-
-```typescript
-// Simple example with all defaults
-@DecoratorName()
-async methodName(): Promise<void> {}
-```
-
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `optionName` | `string` | `'default-value'` | Clear description of what this does |
-| `enabled` | `boolean` | `true` | Whether the feature is enabled |
-| `callback` | `function` | `undefined` | Optional callback function |
-
-### Examples
-
-#### Custom Name
-
-```typescript
-@DecoratorName({ optionName: 'CustomValue' })
-async methodName(): Promise<void> {}
-```
-
-#### Multiple Options
-
-```typescript
-@DecoratorName({
-  optionName: 'CustomValue',
-  enabled: true
-})
-async methodName(): Promise<void> {}
-```
-
-#### All Options
-
-```typescript
-@DecoratorName({
-  optionName: 'CustomValue',
-  enabled: true,
-  callback: () => console.log('done')
-})
-async methodName(): Promise<void> {}
-```
-
-### Behavior
-
-- **Default Behavior**: What happens when you use `@DecoratorName()` with no options
-- **With Options**: How behavior changes with configuration
-- **Side Effects**: Events emitted, lifecycle hooks, etc.
-
-### Type Definition
-
-```typescript
-interface DecoratorNameOptions {
-  optionName?: string;
-  enabled?: boolean;
-  callback?: () => void;
-}
-```
-
-### See Also
-
-- [Related Decorator](#related-decorator)
-- [Advanced Usage](#advanced-usage)
-```
-
----
-
-## URLs and References
-
-### Groundswell Documentation
-
-1. **Workflow Documentation**
-   - URL: `file:///home/dustin/projects/groundswell/docs/workflow.md`
-   - Contains: @Step, @Task, @ObservedState decorator documentation
-   - Pattern: Progressive examples + reference tables
-
-2. **Main README**
-   - URL: `file:///home/dustin/projects/groundswell/README.md`
-   - Contains: Quick start decorator usage
-   - Pattern: Inline comments with code examples
-
-3. **Type Definitions**
-   - URL: `file:///home/dustin/projects/groundswell/src/types/decorators.ts`
-   - Contains: TypeScript interfaces for decorator options
-   - Pattern: JSDoc comments in source code
-
-4. **Example Code**
-   - URL: `file:///home/dustin/projects/groundswell/examples/examples/02-decorator-options.ts`
-   - Contains: Executable examples of all decorator options
-   - Pattern: Comprehensive inline documentation
-
-### External Libraries (For Reference)
-
-**Note:** The following URLs are recommended for further study but could not be accessed during research due to API rate limits. These should be verified and consulted:
-
-5. **class-validator**
-   - Repository: https://github.com/typestack/class-validator
-   - Known for: Extensive decorator options documentation
-   - Study focus: Table formatting, default value presentation
-
-6. **TypeORM**
-   - Repository: https://github.com/typeorm/typeorm
-   - Documentation: https://typeorm.io/#/decorator-reference
-   - Known for: Entity and column decorator options
-   - Study focus: Complex option configuration
-
-7. **NestJS**
-   - Repository: https://github.com/nestjs/nest
-   - Documentation: https://docs.nestjs.com/custom-decorators
-   - Known for: Clean decorator API design
-   - Study focus: Decorator composition patterns
-
-8. **Angular**
-   - Repository: https://github.com/angular/angular
-   - Documentation: https://angular.io/guide/styleguide#style-05-12
-   - Known for: Consistent decorator documentation
-   - Study focus: Documentation style guide
-
-9. **InversifyJS**
-   - Repository: https://github.com/inversify/InversifyJS
-   - Known for: Dependency injection decorators
-   - Study focus: Optional vs required parameters
-
-### Additional Resources
-
-10. **TypeScript Decorator Documentation**
-    - URL: https://www.typescriptlang.org/docs/handbook/decorators.html
-    - Official TypeScript handbook on decorators
-
-11. **TSDoc Standard**
-    - URL: https://tsdoc.org/
-    - Documentation comment standard for TypeScript
-
-12. **JSDoc Documentation**
-    - URL: https://jsdoc.app/
-    - Traditional JavaScript documentation tags
-
----
-
-## Action Items for Groundswell
-
-### Immediate Improvements
-
-1. **Add Default Column** to all decorator option tables
-2. **Document Default Behavior** explicitly before showing options
-3. **Add Type Definitions** section to each decorator doc
-4. **Cross-Link** between related decorators
-
-### Long-term Enhancements
-
-1. **Create Decorator Quick Reference** card
-2. **Add Migration Guide** for decorator option changes
-3. **Generate Documentation** from JSDoc comments
-4. **Add Visual Diagrams** for decorator behavior
-
-### Sample PRP Section
-
-For the `trackTiming` default value documentation task:
-
-```markdown
-### Documentation Update
-
-**File to Update:** `docs/workflow.md`
-
-**Current State:**
-```markdown
-| `trackTiming` | `boolean` | Track and emit step duration |
-```
-
-**Target State:**
-```markdown
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `trackTiming` | `boolean` | `true` | Track and emit step duration |
-```
-
-**Validation:**
-- All three decorators (@Step, @Task, @ObservedState) updated consistently
-- Type definitions in `src/types/decorators.ts` remain accurate
-- Examples in `examples/02-decorator-options.ts` still valid
-```
-
----
-
-## Conclusion
-
-The research shows that **explicit default values in a dedicated column** combined with **progressive code examples** creates the most effective decorator documentation. The Groundswell project already follows many best practices but can be improved by making defaults more visible in tables.
-
-**Key Takeaway:** Documentation should reduce cognitive load by making defaults explicit, not hidden in prose or implied by absence.
-
----
-
-**Document Status:** Research Complete
-**Confidence Score:** 9/10
-**Next Action:** Apply findings to improve decorator documentation in Groundswell