| name | plan |
| description | Epic decomposition into trackable, right-sized tasks. Three modes — audit-aware (codebase-audit reports), workflow-audit-aware (handoff.yaml with pre-rated findings), standalone (from scratch). Light convention scanning for projects without CLAUDE.md. |
| version | 1.3.0 |
| author | Terry Nyberg |
| license | Apache-2.0 |
| allowed-tools | ["Glob","Grep","Read","Write","AskUserQuestion"] |
| metadata | {"tier":"analysis","category":"planning"} |
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 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_scannedsummary 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:
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"
Group Hint Processing
Read group_hint values from issues. Use them as suggestions for task grouping in Step 7:
- Issues sharing a
group_hint are candidates for a single task
- Respect T-shirt sizing rules — don't create L-sized tasks just to honor hints
- Hints are suggestions, not mandates
Produce Handoff Digest
## Handoff Digest
| Field | Value |
|-------|-------|
| Project | [name] |
| Audit Date | [date] |
| Files Scanned | [count] |
| Total Issues | [count] |
### Issue Summary (from audit)
| # | Finding | Urgency | Risk: Fix | Risk: No Fix | ROI | Blast Radius | Fix Effort | Group Hint | Stale? |
|---|---------|---------|-----------|--------------|-----|--------------|------------|------------|--------|
| 1 | [finding] | [urgency] | [risk_fix] | [risk_no_fix] | [roi] | [blast] | [effort] | [hint] | [Yes/No] |
### Staleness Warnings (if any)
| File | Audit Date | Current Date | Affected Issues |
|------|------------|--------------|-----------------|
| [path] | [date] | [date] | #1, #4 |
Step 2D: Light Convention Scanning (workflow-audit-aware and standalone modes)
Skip in audit-aware mode (codebase audit provides enough context).
Skip if project has a comprehensive CLAUDE.md (>100 lines with code patterns).
Detect project conventions automatically when no CLAUDE.md is available:
grep -r "#if os(" Sources/ | head -5
grep -rl "@Model" Sources/ | head -3
grep -rl "NSManagedObject" Sources/ | head -3
grep -rl "GRDB" Sources/ | head -3
grep -rl "HapticManager\|UINotificationFeedbackGenerator" Sources/ | head -3
grep -rl "ToastManager\|toast\|snackbar" Sources/ | head -3
grep -rl "\.alert.*destructive\|confirmationDialog" Sources/ | head -3
grep -rl "NavigationSplitView\|TabView\|NavigationStack" Sources/ | head -3
Output: Detected Conventions Table
Display before planning begins:
## Detected Conventions
| Convention | Detected | Evidence |
|------------|----------|----------|
| Platforms | iOS + macOS | `#if os(iOS)` in 45 files |
| Data Framework | SwiftData | `@Model` in 12 files |
| Haptic Feedback | Yes | `HapticManager` in 8 files |
| Toast/Notifications | Yes | `ToastManager` in 15 files |
| Confirmation Dialogs | Yes | `.alert` with destructive in 22 files |
| Navigation | NavigationSplitView + TabView | Split view in 3 files, TabView in 1 |
This informs fix planning (e.g., "this project uses HapticManager, so feedback fixes should use it too").
Step 3: Interactive Input
IMPORTANT: Use AskUserQuestion to gather requirements.
Common questions (both modes)
AskUserQuestion with questions:
[
{
"question": "What type of work are you planning?",
"header": "Work Type",
"options": [
{"label": "New feature", "description": "Adding new functionality to the app"},
{"label": "Bug fix / improvement", "description": "Fixing issues or enhancing existing features"},
{"label": "Refactoring", "description": "Restructuring code without changing behavior"},
{"label": "Audit remediation", "description": "Fixing findings from a codebase audit or report card"}
],
"multiSelect": false
},
{
"question": "What is your risk tolerance?",
"header": "Risk",
"options": [
{"label": "Conservative", "description": "Minimize risk, smaller incremental changes"},
{"label": "Balanced", "description": "Reasonable risk for reasonable gains"},
{"label": "Aggressive", "description": "Accept higher risk for faster delivery"}
],
"multiSelect": false
},
{
"question": "What is your timeline?",
"header": "Timeline",
"options": [
{"label": "Urgent (days)", "description": "Must ship this week"},
{"label": "Normal (1-2 weeks)", "description": "Standard development cycle"},
{"label": "Flexible (weeks+)", "description": "No immediate deadline"}
],
"multiSelect": false
}
]
Scope question (audit-aware and workflow-audit-aware modes)
After the common questions, also ask:
AskUserQuestion with questions:
[
{
"question": "What scope should the plan cover?",
"header": "Scope",
"options": [
{"label": "Blockers only", "description": "Incomplete triggers + DO NOT SHIP items only"},
{"label": "Top 10 issues", "description": "The 10 highest-priority findings from the report"},
{"label": "All findings", "description": "Comprehensive plan covering every finding"},
{"label": "Pick specific items", "description": "I'll choose which findings to include"}
],
"multiSelect": false
}
]
If "Pick specific items" is selected, present the numbered findings list and ask which to include.
In standalone mode, ask for the feature/task description if not already provided via command arguments.
Step 4: Understanding Phase
Standalone mode output
Feature Summary Table
| Aspect | Details |
|---|
| What | [Restate the feature/task in your own words] |
| Why | [User benefit or business value] |
| Scope | [What's included and excluded] |
User Stories Table
| # | As a... | I want... | So that... |
|---|
| 1 | [user type] | [capability] | [benefit] |
| 2 | [user type] | [capability] | [benefit] |
Acceptance Criteria Table
| # | Criterion | How to Verify |
|---|
| 1 | [What must be true] | [Test or check] |
| 2 | [What must be true] | [Test or check] |
Audit-aware mode output
Issue Summary Table
| # | Category | Issue | Urgency | Risk | ROI | Blast | LOE | Blocker? |
|---|
| 1 | [cat] | [short description] | H/M/L | H/M/L | H/M/L | H/M/L | [Xh] | Yes/No |
| 2 | [cat] | [short description] | H/M/L | H/M/L | H/M/L | H/M/L | [Xh] | Yes/No |
Blocker? = Yes if the finding is an Incomplete trigger or DO NOT SHIP item.
Step 5: T-Shirt Sizing
Apply T-shirt sizes to every task before building the phased plan.
Size Definitions
| Size | Files Touched | Typical Scope | Target |
|---|
| S | 1-2 files | Single fix, one-liner, config change | Combine sequential S tasks into one work unit |
| M | 3-5 files | Feature area fix, cross-cutting concern | Ideal task size — most tasks should be M |
| L | 5+ files | Architectural change, multi-system refactor | Split into 2-3 M tasks |
Sizing Rules
- Target M — Most tasks should touch 3-5 files. This is the sweet spot for reviewable, testable work units.
- Combine S — Two or three sequential S tasks in the same area become one M task.
- Split L — Any task touching 5+ files must be split. Find natural boundaries (model vs view vs tests).
- Minimize overlap — Tasks in the same phase should not modify the same files. If two tasks both touch
ItemListView.swift, combine them or reorder to eliminate conflicts.
- Count tests separately — If a task requires test changes, the test file counts toward the file total.
Sizing Output
After sizing, annotate each task:
Task: "Add keyboard dismissal to item entry forms"
Size: M (4 files: AddItemView, EditItemView, AddItemViewModel, EditItemViewModel)
Step 6: Impact Analysis Table
| Area | Files Affected | Risk Level | Notes |
|---|
| Models | [list] | High/Med/Low | [details] |
| ViewModels | [list] | High/Med/Low | [details] |
| Views | [list] | High/Med/Low | [details] |
| Services/Managers | [list] | High/Med/Low | [details] |
| Tests | [list] | High/Med/Low | [details] |
In audit-aware mode, populate this table from the report findings. Group findings by area and aggregate risk levels.
Step 7: Implementation Plan Table
Audit-aware mode
Include Phase A: Blockers as the first phase if there are Incomplete triggers or DO NOT SHIP items.
| Phase | # | Task | Size | Files | Urgency | Risk | ROI | Blast | LOE | Depends On |
|---|
| A: Blockers | 1 | [Incomplete trigger / DO NOT SHIP fix] | M | [files] | Critical | H | H | [scope] | [Xh] | - |
| A: Blockers | 2 | [Next blocker fix] | M | [files] | Critical | H | H | [scope] | [Xh] | - |
| B: High Priority | 3 | [HIGH severity fix] | M | [files] | H | M | H | [scope] | [Xh] | Phase A |
| B: High Priority | 4 | [HIGH severity fix] | M | [files] | H | M | H | [scope] | [Xh] | Task 3 |
| C: Medium Priority | 5 | [MEDIUM finding] | M | [files] | M | M | M | [scope] | [Xh] | Phase B |
| D: Low / Polish | 6 | [LOW finding / improvement] | S | [files] | L | L | M | [scope] | [Xh] | - |
Each task row MUST include:
- Size: S/M/L (from Step 5)
- Urgency: How soon this needs to happen (Critical/H/M/L)
- Risk: What could go wrong (H/M/L)
- ROI: Value delivered per effort (H/M/L)
- Blast: How much of the app is affected (H/M/L or specific scope like "ItemList feature")
- LOE: Estimated hours
- Depends On: Task # or Phase that must complete first
Standalone mode
Same table structure, but no Phase A: Blockers. Use standard phasing:
| Phase | # | Task | Size | Files | Urgency | Risk | ROI | Blast | LOE | Depends On |
|---|
| A: Foundation | 1 | [Foundation task] | M | [files] | H | L | H | [scope] | [Xh] | - |
| B: Core Logic | 2 | [Core implementation] | M | [files] | H | M | H | [scope] | [Xh] | Phase A |
| C: UI Integration | 3 | [UI work] | M | [files] | M | M | H | [scope] | [Xh] | Phase B |
| D: Polish | 4 | [Polish / edge cases] | S | [files] | L | L | M | [scope] | [Xh] | Phase C |
Task traceability
In audit-aware and workflow-audit-aware modes, every task MUST trace back to its source finding(s):
Task 3: "Fix actor isolation in BackgroundSyncManager"
Source: Audit finding #4 (Concurrency, HIGH)
Size: M (3 files: BackgroundSyncManager.swift, SyncService.swift, SyncServiceTests.swift)
Task 2: "Add confirmation dialogs to 5 destructive actions"
Source: Workflow-audit issues #3, #5, #8, #11, #14 (missing_confirmations)
Size: M (5 files)
Stale: No
Group related findings into single M-sized tasks where they share the same files or logical area. Do NOT create one task per finding — combine related findings. In workflow-audit mode, use group_hint as a starting point for grouping.
Step 8: Risk Assessment Table
| Risk | Likelihood | Impact | Mitigation | Phase |
|---|
| [Risk description] | High/Med/Low | High/Med/Low | [How to mitigate] | [Which phase] |
In audit-aware mode, seed this table from cross-domain correlations in the report (e.g., concurrency issues that affect data persistence).
Step 9: Test Plan Table
| Test Type | What to Test | Priority | Phase |
|---|
| Unit | [Functionality] | High/Med/Low | [Phase letter] |
| Integration | [Functionality] | High/Med/Low | [Phase letter] |
| UI | [Functionality] | High/Med/Low | [Phase letter] |
The Phase column ties each test to its implementation phase — tests for Phase A tasks are written/run during Phase A.
Step 10: Rollback Strategy Table
| Phase | Scenario | Rollback Action |
|---|
| [Phase letter] | [What could go wrong] | [How to undo] |
Per-phase rollback ensures each phase can be independently reverted if needed.
Step 11: Write Output
Display the full implementation plan inline (mode, digest/analysis, feature spec, sizing, impact, phased plan, risks, test plan, rollback), then write to .agents/research/ for future reference:
Write file_path=".agents/research/YYYY-MM-DD-implementation-plan.md" content="[full plan output]"
Use today's date. Include all tables, the mode header, and the report digest (if audit-aware).
Step 12: Deliverables + Proceed
Deliverables Checklist
| Deliverable | Status |
|---|
| Mode detection | Done |
| Report digest (audit) / Codebase analysis (standalone) | Done |
| Feature spec / Issue summary | Done |
| T-shirt sizing | Done |
| Impact analysis | Done |
| Phased implementation plan | Done |
| Risk assessment | Done |
| Test plan | Done |
| Rollback strategy | Done |
| Written to file | Done |
Ready to Proceed?
AskUserQuestion with questions:
[
{
"question": "How would you like to proceed?",
"header": "Action",
"options": [
{"label": "Start Phase A", "description": "Begin implementation with the first phase"},
{"label": "Refine the plan", "description": "Discuss or adjust before starting"},
{"label": "Save for later", "description": "Plan is saved — pick it up anytime"}
],
"multiSelect": false
}
]
Worked Example: Standalone Mode (Abbreviated)
User: "/plan add search feature"
Step 1: Mode = Standalone (no audit reports found)
Step 2B: Codebase analysis — found ItemListView, ItemListViewModel, Item model
Step 3: Work type = New feature, Risk = Balanced, Timeline = Normal
Step 4: Feature spec — search bar filtering items by title, category, notes
Step 5: T-shirt sizing — M (4 files: ItemListView, ItemListViewModel, Item+Search, SearchTests)
Step 6: Impact — Views (1 file), ViewModels (1 file), Models (1 extension), Tests (1 file)
Step 7: Plan
Phase A: Add searchText @State + .searchable to ItemListView (M, 3 files)
Phase B: Unit tests for filter matching (S, 1 file)
Step 8: Risk — Low (additive change)
Step 9: Tests — Unit: filter matching, empty query, case sensitivity (Phase A)
Step 10: Rollback — Revert .searchable modifier, remove filter computed property
Step 11: Written to .agents/research/2026-02-25-implementation-plan.md
Step 12: Ready to proceed?
Troubleshooting
| Problem | Solution |
|---|
| Can't find audit report | Check .agents/research/ for *-codebase-audit.md or *-tech-reportcard.md |
| Report is stale (>14 days) | Run /codebase-audit or /tech-talk-reportcard first, then re-plan |
| Too many findings to plan | Use "Blockers only" or "Top 10 issues" scope to focus |
| Tasks too large (L-sized) | Split along natural boundaries: model/view/test, or by sub-feature |
| Dependencies between phases unclear | Draw the dependency chain from data model → service → viewmodel → view |
| User unclear on scope | Use standalone mode with AskUserQuestion to clarify iteratively |
Worked Example: Audit-Aware Mode (Abbreviated)
User: "/plan --audit" (recent codebase-audit report exists)
Step 1: Mode = Audit-Aware, Report: 2026-02-20-codebase-audit.md (5 days old)
Step 2A: Report Digest
Overall: C+ (77), Incomplete in Security (hardcoded API key)
Ship: DO NOT SHIP
Top 10: 2 CRITICAL, 3 HIGH, 5 MEDIUM
Step 3: Work type = Audit remediation, Risk = Conservative, Scope = Top 10 issues
Step 4: Issue Summary — 10 rows with Urgency/Risk/ROI/Blast/LOE, 1 blocker
Step 5: T-shirt sizing — grouped into 6 M-sized tasks + 1 S task
Step 6: Impact — Models (2 files), Services (3 files), Views (4 files), Tests (3 files)
Step 7: Plan
Phase A: Blockers — Remove hardcoded API key, move to Keychain (M, 3 files)
Phase B: High — Fix actor isolation in SyncManager, add missing @MainActor (M, 4 files)
Phase C: Medium — Add accessibility labels, fix Dynamic Type (M, 5 files → split into 2 tasks)
Step 8: Risk — Keychain migration could break existing users (Phase A, mitigate with fallback read)
Step 9: Tests — Unit: Keychain wrapper (A), actor isolation (B), accessibility (C)
Step 10: Rollback — Phase A: revert Keychain, restore inline key. Phase B: revert actor changes.
Step 11: Written to .agents/research/2026-02-25-implementation-plan.md
Step 12: Ready to proceed?
