plan
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.
Terry Nyberg · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Terryc21/workflow-audit --skill planAbout this skill
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.mdfor 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. The two worked examples at the end of this file show the 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
Read the complete source ↗