Plan Lint

Overview

Validates chunked plan files for structural consistency. This is automated checking — fast and mechanical.

Announce at start: "Using ddd-workflow:plan-lint to validate plan structure."

What This Checks

Process

┌─────────────────────────────────────────────────────────┐
│                    LINT LOOP                            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   1. Read docs/plans/00-conventions.md (if exists)      │
│   2. Read ALL chunk files                               │
│   3. Analyze for inconsistencies                        │
│   4. Report findings to user                            │
│                                                         │
│               Issues found?                             │
│                 ↓         ↓                             │
│               Yes         No                            │
│                ↓           ↓                            │
│           Fix issues    Done ✓                          │
│                ↓                                        │
│           Re-run lint ──────────────────┐               │
│                ↑                        │               │
│                └────────────────────────┘               │
│                                                         │
└─────────────────────────────────────────────────────────┘

Step 1: Gather Context

Read in this order:

1. docs/plans/00-conventions.md - The authoritative conventions (if exists)
2. 00-overview.md - Understand the plan structure
3. All numbered chunk files (01-*.md, 02-*.md, etc.)

Step 2: Analyze for Inconsistencies

Naming Pattern Analysis

Look for semantic equivalents with different names:

Guard clauses:
- ensure_*()      → "ensure user is valid"
- assert_*()      → "assert user is valid"
- *_or_raise()    → "validate user or raise"
- require_*()     → "require user"

Factory methods:
- create_*()      → "create order"
- make_*()        → "make order"
- build_*()       → "build order"
- new_*()         → "new order"

Validation:
- validate_*()    → "validate input"
- check_*()       → "check input"
- is_valid_*()    → "is valid input"

Flag if: Same semantic operation uses different naming patterns across chunks.

Detail Level Analysis

Scan each chunk for vague instructions:

Red flags (insufficient detail):

• "implement the tests for X"
• "add validation"
• "handle errors appropriately"
• "follow the pattern from chunk N"
• "similar to above"
• Missing actual code blocks where code is expected

Expected (sufficient detail):

• Actual test code with assertions
• Actual implementation code
• Specific error messages
• Exact file paths
• Expected command output

Design Decisions Analysis

For each chunk:

1. Determine if it's "non-trivial" (has patterns, architectural choices, trade-offs)
2. Check if ## Design Decisions section exists
3. If non-trivial but missing, flag for addition

Cross-reference decisions:

• Extract all Design Decisions from all chunks
• Check for consistency (e.g., "ensure_* convention" should match usage everywhere)
• Compare against docs/plans/00-conventions.md
• Flag contradictions or undocumented decisions

Structure Consistency

Compare section headers across chunks:

Chunk 1: Files, Design Decisions, Step 1, Step 2, Step 3, Step 4, Step 5
Chunk 2: Files, Step 1, Step 2, Step 3
Chunk 3: Files, Steps 1-3, Implementation, Commit

Flag if: Chunks use different structural patterns without clear reason.

Length Variance

Calculate line counts:

• Mean line count across chunks
• Standard deviation
• Flag outliers (>2x mean or <0.5x mean)

Step 3: Report Findings

Present issues in a structured format:

## Plan Lint Results

### Naming Inconsistencies
| Pattern | Used In | Recommendation |
|---------|---------|----------------|
| `ensure_valid()` | 01, 03, 07 | Standardize on this |
| `assert_valid()` | 02, 05 | Change to `ensure_*` |

### Detail Level Issues
| Chunk | Line | Issue |
|-------|------|-------|
| 04-auth.md | 45 | "implement validation" - needs actual code |
| 08-api.md | 23 | "handle errors" - needs specific error handling |

### Design Decision Issues
| Chunk | Issue |
|-------|-------|
| 14-user-entity.md | Has State Pattern impl but no Design Decisions section |
| 19-uc-register.md | References "ensure_*" but decision not in conventions |

### Structure Variations
- Chunks 1-5: Use "Step N" format
- Chunks 6-8: Use "Phase N" format
- Recommendation: Standardize on "Step N"

### Length Outliers
| Chunk | Lines | Issue |
|-------|-------|-------|
| 12-integration.md | 487 | 2.4x average - consider splitting |

Step 4: Fix Issues

IMPORTANT: Any updates to docs/plans/00-conventions.md require user approval. Always ask before modifying the conventions file.

For each issue category:

Naming fixes

1. Identify the dominant pattern (most frequently used)
2. Or check docs/plans/00-conventions.md for the authoritative choice
3. Update all non-conforming chunks to use the standard pattern
4. If pattern wasn't in docs/plans/00-conventions.md: Ask user for approval before adding it

Detail level fixes

1. Expand vague instructions into actual code
2. Add missing test assertions
3. Add specific error messages
4. Add expected output for commands

Design Decisions fixes

1. Add missing sections to non-trivial chunks
2. Extract implicit decisions and document them
3. Sync new decisions to docs/plans/00-conventions.md (with user approval)

Structure fixes

1. Identify the most complete structure
2. Add missing sections to incomplete chunks
3. Rename sections for consistency

Length fixes

1. Split overly long chunks into multiple files
2. Expand too-short chunks if they're missing detail
3. Update 00-overview.md task index if chunks are added/split

Step 5: Verify (Re-run)

After fixes, re-run the full lint process:

• If new issues found → fix and re-run
• If clean → report success

Maximum iterations: 3 (prevent infinite loops on edge cases)

If issues persist after 3 iterations, report remaining issues to user for manual review.

Standalone Usage

To lint an existing plan directory:

User: "Lint the plan in docs/plans/2024-01-15-auth-system/"

The skill will:

1. Read all files in that directory
2. Run the full lint process
3. Offer to fix issues found

Output on Success

## Plan Lint: PASSED ✓

- 12 chunks analyzed
- 0 naming inconsistencies
- 0 detail level issues
- 0 Design Decision issues
- 0 structure variations
- All chunks within normal length range

Plan is ready for architectural review (ddd-workflow:plan-review).