@leeovery/claude-technical-workflows 2.0.44 → 2.0.46

package/skills/technical-planning/references/steps/plan-review.md

@@ -0,0 +1,96 @@
+# Plan Review
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+After completing the plan, perform a comprehensive two-part review before handing off to implementation.
+
+**Why this matters**: The plan is what gets built. If content was hallucinated into the plan, it will be implemented — building something that was never discussed or validated. If specification content was missed, it won't be built. The entire purpose of this workflow is that artifacts carry validated decisions through to implementation. The plan is the final gate before code is written.
+
+## Review Tracking Files
+
+To ensure analysis isn't lost during context refresh, create tracking files that capture findings. These files persist analysis so work can continue across sessions.
+
+**Location**: Store tracking files alongside the plan file:
+- `{topic}-review-traceability-tracking.md` — Traceability findings
+- `{topic}-review-integrity-tracking.md` — Integrity findings
+
+**Format**:
+```markdown
+---
+status: in-progress | complete
+created: YYYY-MM-DD
+phase: Traceability Review | Plan Integrity Review
+topic: [Topic Name]
+---
+
+# Review Tracking: [Topic Name] - [Phase]
+
+## Findings
+
+### 1. [Brief Title]
+
+**Type**: Missing from plan | Hallucinated content | Incomplete coverage | Structural issue | Weak criteria | ...
+**Spec Reference**: [Section/decision in specification, or "N/A" for integrity findings]
+**Plan Reference**: [Phase/task in plan, or "N/A" for missing content]
+
+**Details**:
+[What was found and why it matters]
+
+**Proposed Fix**:
+[What should change in the plan — leave blank until discussed]
+
+**Resolution**: Pending | Fixed | Adjusted | Skipped
+**Notes**: [Discussion notes or adjustments]
+
+---
+
+### 2. [Next Finding]
+...
+```
+
+**Why tracking files**: If context refreshes mid-review, you can read the tracking file and continue where you left off. The tracking file shows which items are resolved and which remain.
+
+---
+
+## Traceability Review
+
+Compare the plan against the specification in both directions — checking that everything from the spec is in the plan, and everything in the plan traces back to the spec.
+
+Load **[review-traceability.md](review-traceability.md)** and follow its instructions as written.
+
+---
+
+## Plan Integrity Review
+
+Review the plan as a standalone document for structural quality, implementation readiness, and adherence to planning standards.
+
+Load **[review-integrity.md](review-integrity.md)** and follow its instructions as written.
+
+---
+
+## Completion
+
+After both reviews:
+
+1. **Verify tracking files are deleted** — Both traceability and integrity tracking files must be gone
+
+2. **Final quality confirmation**:
+   - All specification content has plan coverage (Traceability)
+   - No hallucinated content remains (Traceability)
+   - All tasks follow the required template (Integrity)
+   - Dependencies are documented and ordered (Integrity)
+   - External dependencies match specification (Integrity)
+
+3. **Confirm with the user**:
+
+> "The plan has passed both reviews:
+> - **Traceability**: All specification content is covered; no hallucinated content
+> - **Integrity**: Plan structure, tasks, and dependencies are implementation-ready
+>
+> Review is complete."
+
+> **CHECKPOINT**: Do not confirm completion if tracking files still exist. They indicate incomplete review work.
+
+→ Proceed to **Step 9**.

package/skills/technical-planning/references/steps/resolve-dependencies.md

@@ -0,0 +1,56 @@
+# Resolve External Dependencies
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+Orient the user:
+
+> "All phases and tasks are written. Now I'll check for external dependencies — things this plan needs from other topics or systems."
+
+After all phases are detailed and written, handle external dependencies — things this plan needs from other topics or systems.
+
+#### If the specification has a Dependencies section
+
+The specification's Dependencies section lists what this feature needs from outside its own scope. These must be documented in the plan so implementation knows what is blocked and what is available.
+
+1. **Document each dependency** in the plan's External Dependencies section using the format described in [dependencies.md](../dependencies.md). Initially, record each as unresolved.
+
+2. **Resolve where possible** — For each dependency, check whether a plan already exists for that topic:
+   - If a plan exists, identify the specific task(s) that satisfy the dependency. Query the output format to find relevant tasks. If ambiguous, ask the user which tasks apply. Update the dependency entry from unresolved → resolved with the task reference.
+   - If no plan exists, leave the dependency as unresolved. It will be linked later via `/link-dependencies` or when that topic is planned.
+
+3. **Reverse check** — Check whether any existing plans have unresolved dependencies that reference *this* topic. Now that this plan exists with specific tasks:
+   - Scan other plan files for External Dependencies entries that mention this topic
+   - For each match, identify which task(s) in the current plan satisfy that dependency
+   - Update the other plan's dependency entry with the task reference (unresolved → resolved)
+
+#### If the specification has no Dependencies section
+
+Document this explicitly in the plan:
+
+```markdown
+## External Dependencies
+
+No external dependencies.
+```
+
+This makes it clear that dependencies were considered and none exist — not that they were overlooked.
+
+#### If no other plans exist
+
+Skip the resolution and reverse check — there is nothing to resolve against. Document the dependencies as unresolved. They will be linked when other topics are planned, or via `/link-dependencies`.
+
+**STOP.** Present a summary of the dependency state: what was documented, what was resolved, what remains unresolved, and any reverse resolutions made.
+
+> **To proceed, choose one:**
+> - **"Approve"** — Dependency state is confirmed. Proceed to plan review.
+> - **"Adjust"** — Tell me what to change.
+
+#### If Adjust
+
+Incorporate feedback, re-present the updated dependency state, and ask again. Repeat until approved.
+
+#### If Approved
+
+→ Proceed to **Step 8**.

package/skills/technical-planning/references/steps/review-integrity.md

@@ -0,0 +1,217 @@
+# Plan Integrity Review
+
+*Reference for **[plan-review](plan-review.md)***
+
+---
+
+Review the plan **as a standalone document** for structural quality, implementation readiness, and adherence to planning standards.
+
+**Purpose**: Ensure that the plan itself is well-structured, complete, and ready for implementation. An implementer (human or AI) should be able to pick up this plan and execute it without ambiguity, without needing to make design decisions, and without referring back to the specification.
+
+**Key distinction**: The traceability review checked *what's in the plan* against the spec. This review checks *how it's structured* — looking inward at the plan's own quality.
+
+Read the plan end-to-end — carefully, as if you were about to implement it. For each phase, each task, and the plan overall, check against the following criteria:
+
+## What You're NOT Doing
+
+- **Not redesigning the plan** — You're checking quality, not re-architecting
+- **Not adding content from outside the spec** — If a task needs more detail, the detail must come from the specification
+- **Not gold-plating** — Focus on issues that would actually impact implementation
+- **Not second-guessing phase structure** — Unless it's fundamentally broken, the structure stands
+
+---
+
+## What to Look For
+
+1. **Task Template Compliance**
+   - Every task has all required fields: Problem, Solution, Outcome, Do, Acceptance Criteria, Tests
+   - Problem statements clearly explain WHY the task exists
+   - Solution statements describe WHAT we're building
+   - Outcome statements define what success looks like
+   - Acceptance criteria are concrete and verifiable (not vague)
+   - Tests include edge cases, not just happy paths
+
+2. **Vertical Slicing**
+   - Tasks deliver complete, testable functionality
+   - No horizontal slicing (all models, then all services, then all wiring)
+   - Each task can be verified independently
+   - Each task is a single TDD cycle
+
+3. **Phase Structure**
+   - Phases follow logical progression (Foundation → Core → Edge cases → Refinement)
+   - Each phase has clear acceptance criteria
+   - Each phase is independently testable
+   - Phase boundaries make sense (not arbitrary groupings)
+
+4. **Dependencies and Ordering**
+   - Phase ordering reflects actual dependencies
+   - Tasks within phases are ordered logically
+   - Cross-phase dependencies are explicit where they exist
+   - No circular dependencies
+   - An implementer can infer execution order from the plan structure
+
+5. **Task Self-Containment**
+   - Each task contains all context needed for execution
+   - No task requires reading other tasks to understand what to do
+   - Relevant specification decisions are pulled into task context
+   - An implementer could pick up any single task and execute it
+
+6. **Scope and Granularity**
+   - Each task is one TDD cycle (not too large, not too small)
+   - No task requires multiple unrelated implementation steps
+   - No task is so granular it's just mechanical boilerplate
+
+7. **Acceptance Criteria Quality**
+   - Criteria are pass/fail, not subjective
+   - Criteria cover the actual requirement, not just "code exists"
+   - Edge case criteria are specific about boundary values and behaviors
+   - No criteria that an implementer would have to interpret
+
+8. **External Dependencies**
+   - All external dependencies from the specification are documented in the plan
+   - Dependencies are in the correct state (resolved/unresolved)
+   - No external dependencies were missed or invented
+
+## Presenting Integrity Findings
+
+After completing your review, categorize each finding by severity:
+
+- **Critical**: Would block implementation or cause incorrect behavior
+- **Important**: Would force implementer to guess or make design decisions
+- **Minor**: Polish or improvement that strengthens the plan
+
+Then:
+
+1. **Create the tracking file** — Write all findings to `{topic}-review-integrity-tracking.md`
+2. **Commit the tracking file** — Ensures it survives context refresh
+3. **Present findings** in two stages:
+
+**Stage 1: Summary**
+
+> "I've completed the plan integrity review. I found [N] items:
+>
+> 1. **[Brief title]** (Critical/Important/Minor)
+>    [2-4 line explanation: what the issue is, why it matters for implementation]
+>
+> 2. **[Brief title]** (Critical/Important/Minor)
+>    [2-4 line explanation]
+>
+> Let's work through these one at a time, starting with #1."
+
+**Stage 2: Process One Item at a Time**
+
+Work through each finding **one at a time**. For each finding: present it, propose the fix, wait for approval, then apply it verbatim.
+
+### Present the Finding
+
+Show the finding with full detail:
+
+> **Finding {N} of {total}: {Brief Title}**
+>
+> **Severity**: Critical | Important | Minor
+>
+> **Plan Reference**: [Phase/task in the plan]
+>
+> **Category**: [Which review criterion — e.g., "Task Template Compliance", "Vertical Slicing"]
+>
+> **Details**: [What the issue is and why it matters for implementation]
+
+### Propose the Fix
+
+Present the proposed fix **in the format it will be written to the plan**. What the user sees is what gets applied — no changes between approval and writing.
+
+State the action type explicitly so the user knows what's changing structurally:
+
+**Update a task** — change content within an existing task:
+
+> **Proposed fix — update Phase {N}, Task {M}:**
+>
+> **Current:**
+> [The existing content as it appears in the plan]
+>
+> **Proposed:**
+> [The replacement content]
+
+**Add content to a task** — insert into an existing task (e.g., missing acceptance criteria, edge case):
+
+> **Proposed fix — add to Phase {N}, Task {M}, {section}:**
+>
+> [The exact content to be added, in plan format]
+
+**Remove content from a task** — strip content that shouldn't be there:
+
+> **Proposed fix — remove from Phase {N}, Task {M}, {section}:**
+>
+> [The exact content to be removed]
+
+**Add a new task** — a spec section has no plan coverage and needs its own task:
+
+> **Proposed fix — add new task to Phase {N}:**
+>
+> [The complete task in plan format, using the task template]
+
+**Remove a task** — an entire task is hallucinated with no spec backing:
+
+> **Proposed fix — remove Phase {N}, Task {M}: {Task Name}**
+>
+> **Reason**: [Why this task has no specification basis]
+
+**Add a new phase** — a significant area of the specification has no plan coverage:
+
+> **Proposed fix — add new Phase {N}: {Phase Name}**
+>
+> [Phase goal, acceptance criteria, and task overview]
+
+**Remove a phase** — an entire phase is not backed by the specification:
+
+> **Proposed fix — remove Phase {N}: {Phase Name}**
+>
+> **Reason**: [Why this phase has no specification basis]
+
+After presenting the finding and proposed fix, ask:
+
+> **Finding {N} of {total}: {Brief Title}**
+>
+> **To proceed, choose one:**
+> - **"Approve"** — Fix is confirmed. I'll apply it to the plan verbatim.
+> - **"Adjust"** — Tell me what to change about the proposed fix.
+> - **"Skip"** — Leave this as-is and move to the next finding.
+
+**STOP.** Wait for the user's response.
+
+### If Adjust
+
+The user may:
+- Request changes to the proposed fix
+- Ask questions about why this was flagged
+- Suggest a different approach to resolving the finding
+
+Incorporate feedback and re-present the proposed fix **in full** using the same format above. Then ask the same choice again. Repeat until approved or skipped.
+
+### If Approved
+
+Apply the fix to the plan — as presented, using the output format adapter to determine how it's written. Do not modify content between approval and writing. Then update the tracking file: mark resolution as "Fixed", add any discussion notes.
+
+Confirm:
+
+> "Finding {N} of {total}: {Brief Title} — fixed."
+
+### If Skipped
+
+Update the tracking file: mark resolution as "Skipped", note the reason.
+
+> "Finding {N} of {total}: {Brief Title} — skipped."
+
+### Next Finding
+
+Commit the tracking file (and any plan changes) before moving on. This ensures progress survives context refresh or session interruption.
+
+**If findings remain:** → Present the next finding. Follow the same present → propose → ask → apply sequence.
+
+**If all findings are processed:**
+
+**Delete the integrity tracking file** (`{topic}-review-integrity-tracking.md`) — it has served its purpose.
+
+Inform the user the integrity review is complete.
+
+→ Return to **[plan-review.md](plan-review.md)** for completion.

package/skills/technical-planning/references/steps/review-traceability.md

@@ -0,0 +1,194 @@
+# Traceability Review
+
+*Reference for **[plan-review](plan-review.md)***
+
+---
+
+Compare the plan against the specification **in both directions** to ensure complete, faithful translation.
+
+**Purpose**: Verify that the plan is a faithful, complete translation of the specification. Everything in the spec must be in the plan, and everything in the plan must trace back to the spec. This is the anti-hallucination gate — it catches both missing content and invented content before implementation begins.
+
+Re-read the specification in full before starting. Don't rely on memory — read it as if seeing it for the first time. Then check both directions:
+
+## What You're NOT Doing
+
+- **Not adding new requirements** — If something isn't in the spec, the fix is to remove it from the plan or flag it with `[needs-info]`, not to justify its inclusion
+- **Not expanding scope** — Missing spec content should be added as tasks; it shouldn't trigger re-architecture of the plan
+- **Not being lenient with hallucinated content** — If it can't be traced to the specification, it must be removed or the user must explicitly approve it as an intentional addition
+- **Not re-litigating spec decisions** — The specification reflects validated decisions; you're checking the plan's fidelity to them
+
+---
+
+## Direction 1: Specification → Plan (completeness)
+
+Is everything from the specification represented in the plan?
+
+1. **For each specification element, verify plan coverage**:
+   - Every decision → has a task that implements it
+   - Every requirement → has a task with matching acceptance criteria
+   - Every edge case → has a task or is explicitly handled within a task
+   - Every constraint → is reflected in the relevant tasks
+   - Every data model or schema → appears in the relevant tasks
+   - Every integration point → has a task that addresses it
+   - Every validation rule → has a task with test coverage
+
+2. **Check depth of coverage** — It's not enough that a spec topic is *mentioned* in a task. The task must contain enough detail that an implementer wouldn't need to go back to the specification. Summarizing and rewording is fine, but the essence and instruction must be preserved.
+
+## Direction 2: Plan → Specification (fidelity)
+
+Is everything in the plan actually from the specification? This is the anti-hallucination check.
+
+1. **For each task, trace its content back to the specification**:
+   - The Problem statement → ties to a spec requirement or decision
+   - The Solution approach → matches the spec's architectural choices
+   - The implementation details → come from the spec, not invention
+   - The acceptance criteria → verify spec requirements, not made-up ones
+   - The tests → cover spec behaviors, not imagined scenarios
+   - The edge cases → are from the spec, not invented
+
+2. **Flag anything that cannot be traced**:
+   - Content that has no corresponding specification section
+   - Technical approaches not discussed in the specification
+   - Requirements or behaviors not mentioned anywhere in the spec
+   - Edge cases the specification never identified
+   - Acceptance criteria testing things the specification doesn't require
+
+3. **The standard for hallucination**: If you cannot point to a specific part of the specification that justifies a piece of plan content, it is hallucinated. It doesn't matter how reasonable it seems — if it wasn't discussed and validated, it doesn't belong in the plan.
+
+## Presenting Traceability Findings
+
+After completing your review:
+
+1. **Create the tracking file** — Write all findings to `{topic}-review-traceability-tracking.md`
+2. **Commit the tracking file** — Ensures it survives context refresh
+3. **Present findings** in two stages:
+
+**Stage 1: Summary**
+
+> "I've completed the traceability review comparing the plan against the specification. I found [N] items:
+>
+> 1. **[Brief title]** (Missing from plan | Hallucinated | Incomplete)
+>    [2-4 line explanation: what's wrong, where in the spec/plan, why it matters]
+>
+> 2. **[Brief title]** (Missing from plan | Hallucinated | Incomplete)
+>    [2-4 line explanation]
+>
+> Let's work through these one at a time, starting with #1."
+
+**Stage 2: Process One Item at a Time**
+
+Work through each finding **one at a time**. For each finding: present it, propose the fix, wait for approval, then apply it verbatim.
+
+### Present the Finding
+
+Show the finding with full detail:
+
+> **Finding {N} of {total}: {Brief Title}**
+>
+> **Type**: Missing from plan | Hallucinated content | Incomplete coverage
+>
+> **Spec Reference**: [Section/decision in the specification]
+>
+> **Plan Reference**: [Phase/task in the plan, or "N/A" for missing content]
+>
+> **Details**: [What's wrong and why it matters]
+
+### Propose the Fix
+
+Present the proposed fix **in the format it will be written to the plan**. What the user sees is what gets applied — no changes between approval and writing.
+
+State the action type explicitly so the user knows what's changing structurally:
+
+**Update a task** — change content within an existing task:
+
+> **Proposed fix — update Phase {N}, Task {M}:**
+>
+> **Current:**
+> [The existing content as it appears in the plan]
+>
+> **Proposed:**
+> [The replacement content]
+
+**Add content to a task** — insert into an existing task (e.g., missing acceptance criteria, edge case):
+
+> **Proposed fix — add to Phase {N}, Task {M}, {section}:**
+>
+> [The exact content to be added, in plan format]
+
+**Remove content from a task** — strip content that shouldn't be there:
+
+> **Proposed fix — remove from Phase {N}, Task {M}, {section}:**
+>
+> [The exact content to be removed]
+
+**Add a new task** — a spec section has no plan coverage and needs its own task:
+
+> **Proposed fix — add new task to Phase {N}:**
+>
+> [The complete task in plan format, using the task template]
+
+**Remove a task** — an entire task is hallucinated with no spec backing:
+
+> **Proposed fix — remove Phase {N}, Task {M}: {Task Name}**
+>
+> **Reason**: [Why this task has no specification basis]
+
+**Add a new phase** — a significant area of the specification has no plan coverage:
+
+> **Proposed fix — add new Phase {N}: {Phase Name}**
+>
+> [Phase goal, acceptance criteria, and task overview]
+
+**Remove a phase** — an entire phase is not backed by the specification:
+
+> **Proposed fix — remove Phase {N}: {Phase Name}**
+>
+> **Reason**: [Why this phase has no specification basis]
+
+After presenting the finding and proposed fix, ask:
+
+> **Finding {N} of {total}: {Brief Title}**
+>
+> **To proceed, choose one:**
+> - **"Approve"** — Fix is confirmed. I'll apply it to the plan verbatim.
+> - **"Adjust"** — Tell me what to change about the proposed fix.
+> - **"Skip"** — Leave this as-is and move to the next finding.
+
+**STOP.** Wait for the user's response.
+
+### If Adjust
+
+The user may:
+- Request changes to the proposed fix
+- Ask questions about why this was flagged
+- Suggest a different approach to resolving the finding
+
+Incorporate feedback and re-present the proposed fix **in full** using the same format above. Then ask the same choice again. Repeat until approved or skipped.
+
+### If Approved
+
+Apply the fix to the plan — as presented, using the output format adapter to determine how it's written. Do not modify content between approval and writing. Then update the tracking file: mark resolution as "Fixed", add any discussion notes.
+
+Confirm:
+
+> "Finding {N} of {total}: {Brief Title} — fixed."
+
+### If Skipped
+
+Update the tracking file: mark resolution as "Skipped", note the reason.
+
+> "Finding {N} of {total}: {Brief Title} — skipped."
+
+### Next Finding
+
+Commit the tracking file (and any plan changes) before moving on. This ensures progress survives context refresh or session interruption.
+
+**If findings remain:** → Present the next finding. Follow the same present → propose → ask → apply sequence.
+
+**If all findings are processed:**
+
+**Delete the traceability tracking file** (`{topic}-review-traceability-tracking.md`) — it has served its purpose.
+
+Inform the user the traceability review is complete.
+
+→ Return to **[plan-review.md](plan-review.md)** for the integrity review.