plan

Implementation Plan Generator

Quick Ref: Mode detect → ingest or analyze → interactive input → understand → size → impact → phased plan → risk → test → rollback → write → proceed.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Required output: Every task MUST include Size, Urgency, Risk, ROI, Blast Radius, and LOE ratings. Do not omit these ratings.

Rating format: See radar-suite-core.md for column definitions, indicator scale, and table formatting rules.

Pre-flight: Git Safety Check

git status --short

If uncommitted changes exist:

AskUserQuestion with questions:
[
  {
    "question": "You have uncommitted changes. Commit before proceeding?",
    "header": "Git",
    "options": [
      {"label": "Commit first (Recommended)", "description": "Save current work so you can revert if this skill modifies files"},
      {"label": "Continue without committing", "description": "Proceed — I accept the risk"}
    ],
    "multiSelect": false
  }
]

If "Commit first": Ask for a commit message, stage changed files, and commit. Then proceed.

Golden Rule

Plans describe WHAT to change and WHERE — never HOW.

A plan task says: "Add keyboard dismissal to AddItemView.swift:45-80 and EditItemView.swift:32-60. Acceptance: tapping outside any text field dismisses the keyboard."

A plan task does NOT say: "Add .onTapGesture { UIApplication.shared.sendAction(#selector(UIResponder.resignFirstResponder)...) }"

Exception: Include code (≤10 lines) ONLY when referencing an existing pattern in the repo, showing a required API signature, or documenting a known framework gotcha. See [examples.md](examples.md) for calibration.

Step 1: Mode Detection

Detect which mode to run in: audit-aware, workflow-audit-aware, or standalone.

# Check for codebase audit reports
Glob pattern=".agents/research/*-codebase-audit.md"
Glob pattern=".agents/research/*-tech-reportcard.md"

# Check for workflow audit handoff
Glob pattern=".workflow-audit/handoff.yaml"

Decision logic:

| Condition | Mode | |-----------|------| | User passes --workflow-audit | Workflow-audit-aware (error if no handoff found) | | User specifies audit mode | Audit-aware (error if no report found) | | User specifies standalone mode | Standalone (ignore all reports) | | .workflow-audit/handoff.yaml found AND audit_date <14 days | Workflow-audit-aware | | Codebase audit report found AND <14 days old | Audit-aware | | Report found AND ≥14 days old | Standalone (warn: "Stale audit report found — run /codebase-audit for fresh data") | | Both workflow-audit and codebase-audit found | Workflow-audit-aware takes priority (more specific) | | No report found | Standalone |

Parse the report filename date: YYYY-MM-DD-codebase-audit.md or YYYY-MM-DD-tech-reportcard.md. Parse audit_date from handoff.yaml for workflow-audit mode.

If multiple reports exist, use the most recent one.

Mode summary:

| Mode | Source | Ratings Pre-computed? | Convention Scan? | |------|--------|-----------------------|------------------| | Audit-aware | .agents/research/*-codebase-audit.md | No — extract and rate | No — uses audit context | | Workflow-audit-aware | .workflow-audit/handoff.yaml | Yes — use as-is | Yes — if no CLAUDE.md | | Standalone | User-provided task description | No — rate from scratch | Yes — if no CLAUDE.md |

Output:

## Mode: [Audit-Aware / Workflow-Audit-Aware / Standalone]
Report: [filename or "none"]
Report age: [N days or "n/a"]
Staleness warnings: [count or "none"]

Step 2A: Audit Ingest (audit-aware mode only)

Skip this step in standalone mode — go to Step 2B.

Read the audit report and extract structured data.

Read file_path=".agents/research/[report-filename]"

Parse grades

Look for the GRADES_YAML HTML comment block first:

<!-- GRADES_YAML
categories:
  - name: Architecture
    score: 91
    grade: A-
    ...
-->

If no YAML block, fall back to parsing the grade summary line:

**Overall: B+ (84)** (Arch A- [91] | Security C+ [77] | ...)

Extract Top 10 Issues

Scan the report for the prioritized findings list. Each finding should have:

• Category
• Severity (CRITICAL / HIGH / MEDIUM / LOW)
• Description
• File:line reference
• LOE estimate

Detect special conditions

| Condition | What to extract | |-----------|----------------| | Incomplete (I) grade | Category name + trigger description + file:line | | DO NOT SHIP recommendation | All blocker items listed under the recommendation | | CRITICAL findings | Full finding details |

Produce Report Digest

## Report Digest

| Source | Date | Overall Grade |
|--------|------|---------------|
| [codebase-audit / tech-reportcard] | [date] | [grade] |

### Incomplete Triggers (if any)
| Category | Trigger | File |
|----------|---------|------|
| [category] | [description] | [file:line] |

### Ship Recommendation
[SHIP / CONDITIONAL SHIP / DO NOT SHIP] — [reason]

### Top Issues
| # | Category | Severity | Issue | File | LOE |
|---|----------|----------|-------|------|-----|
| 1 | [cat] | CRITICAL | [desc] | [file:line] | [Xh] |
| 2 | [cat] | HIGH | [desc] | [file:line] | [Xh] |
| ... | | | | | |

Step 2B: Codebase Analysis (standalone mode only)

Skip this step in audit-aware mode — audit already did this work.

Freshness

Base all analysis on current source code only. Do not read or reference files in .agents/, scratch/, or prior audit reports (those are ingested in Step 2A only). Every finding must come from scanning the actual codebase as it exists now.

Scan the codebase for context relevant to the planned work:

# Find files related to the feature area
Glob pattern="**/*FeatureName*.swift"
Grep pattern="FeatureKeyword" glob="**/*.swift" output_mode="files_with_matches"

# Find existing patterns to follow
Grep pattern="class.*ViewModel|struct.*View.*body" glob="**/*.swift" output_mode="files_with_matches"

# Find dependencies that will be affected
Grep pattern="import.*ModuleName|ModuleName\\." glob="**/*.swift" output_mode="files_with_matches"

# Find test files for affected areas
Glob pattern="Tests/**/*FeatureName*Tests.swift"

Produce:

Related Code Table

| File/Module | Relevance | Notes | |-------------|-----------|-------| | [path] | High/Med/Low | [How it relates] |

Patterns to Follow Table

| Pattern | Example Location | Apply To | |---------|------------------|----------| | [Pattern name] | [File path] | [Where to use] |

Dependencies Table

| This Feature Depends On | Type | |-------------------------|------| | [Module/file] | Required/Optional |

| This Feature Will Affect | Impact | |--------------------------|--------| | [Module/file] | High/Med/Low |

Step 2C: Workflow Audit Ingest (workflow-audit-aware mode only)

Skip this step in audit-aware or standalone mode.

Read the workflow audit handoff brief and ingest pre-rated findings.

Read file_path=".workflow-audit/handoff.yaml"

Parse Handoff Brief

Extract:

• project, audit_date, source_files_scanned
• summary counts (critical/high/medium/low)
• All issues[] with their pre-computed ratings

Ratings are pre-computed — do NOT re-rate issues from the handoff brief. The audit skill already applied the rating system. Use the ratings as-is for planning.

Staleness Check

Compare file_timestamps from the handoff against current file modification dates:

# For each file in file_timestamps, check if it changed
stat -f "%Sm" -t "%Y-%m-%dT%H:%M:%SZ" "<file path>"

If files changed since audit:

• List changed files and affected issue IDs
• Warn but do NOT block: "These issues may need spot-checking during implementation"
• Flag affected issues in the plan output

If audit_date >14 days old:

• Warn: "Workflow audit is stale — consider re-running /workflow-audit for fresh data"

G