@leeovery/claude-technical-workflows 2.0.45 → 2.0.46

package/skills/technical-planning/references/planning-principles.md

@@ -0,0 +1,44 @@
+# Planning Principles
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+This reference defines the principles, rules, and quality standards for creating implementation plans. It is loaded at the start of the planning process and stays in context throughout.
+
+## Planning is a Gated Process
+
+Planning translates the specification into actionable structure. This translation requires judgment, and the process is designed to ensure that judgment is exercised carefully and collaboratively — not rushed.
+
+### Process Expectations
+
+**This is a step-by-step process with mandatory stop points.** You must work through each step sequentially. Steps end with **STOP** — you must present your work, wait for explicit user confirmation, and only then proceed to the next step.
+
+**Never one-shot the plan.** Do not write the entire plan document in a single operation. The plan is built incrementally — one phase at a time, with the user confirming the structure at each stage. A one-shot plan that misses requirements, hallucinates content, or structures tasks poorly wastes more time than a careful, step-by-step process. Go slow to go fast.
+
+**Stop and ask when judgment is needed.** Planning is collaborative — not in the sense that every line needs approval, but in the sense that the user guides structural decisions and resolves ambiguity. You must stop and ask when:
+
+- The specification is ambiguous about implementation approach
+- Multiple valid ways to structure phases or tasks exist
+- You're uncertain whether a task is appropriately scoped
+- Edge cases aren't fully addressed in the specification
+- You need to make any decision the specification doesn't cover
+- Something doesn't add up or feels like a gap
+
+**Never invent to fill gaps.** If the specification doesn't address something, flag it with `[needs-info]` and ask the user. The specification is the golden document — everything in the plan must trace back to it. Assuming or guessing — even when it seems reasonable — is not acceptable. Surface the problem immediately rather than continuing and hoping to address it later.
+
+## Rules
+
+**Capture immediately**: After each user response, update the planning document BEFORE your next question. Never let more than 2-3 exchanges pass without writing.
+
+**Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work.
+
+**Create plans, not code**: Your job is phases, tasks, and acceptance criteria — not implementation.
+
+## Plan as Source of Truth
+
+The plan IS the source of truth. Every phase, every task must contain all information needed to execute it.
+
+- **Self-contained**: Each task executable without external context
+- **No assumptions**: Spell out the context, don't assume implementer knows it
+

package/skills/technical-planning/references/steps/author-tasks.md

@@ -0,0 +1,63 @@
+# Author Tasks
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+Load **[task-design.md](../task-design.md)** — the task design principles, template structure, and quality standards for writing task detail.
+
+---
+
+Orient the user:
+
+> "Task list for Phase {N} is agreed. I'll work through each task one at a time — presenting the full detail, discussing if needed, and logging it to the plan once approved."
+
+Work through the agreed task list **one task at a time**.
+
+#### Present
+
+Write the complete task using the task template — Problem, Solution, Outcome, Do, Acceptance Criteria, Tests, Context.
+
+Present it to the user **in the format it will be written to the plan**. The output format adapter determines the exact format. What the user sees is what gets logged — no changes between approval and writing.
+
+After presenting, ask:
+
+> **Task {M} of {total}: {Task Name}**
+>
+> **To proceed, choose one:**
+> - **"Approve"** — Task is confirmed. I'll log it to the plan verbatim.
+> - **"Adjust"** — Tell me what to change.
+
+**STOP.** Wait for the user's response.
+
+#### If adjust
+
+The user may:
+- Request changes to the task content
+- Ask questions about scope, granularity, or approach
+- Flag that something doesn't match the specification
+- Identify missing edge cases or acceptance criteria
+
+Incorporate feedback and re-present the updated task **in full**. Then ask the same choice again. Repeat until approved.
+
+#### If approved
+
+Log the task to the plan — verbatim, as presented. Do not modify content between approval and writing. The output format adapter determines how tasks are written (appending markdown, creating issues, etc.).
+
+After logging, confirm:
+
+> "Task {M} of {total}: {Task Name} — logged."
+
+#### Next task or phase complete
+
+**If tasks remain in this phase:** → Return to the top of **Step 6** with the next task. Present it, ask, wait.
+
+**If all tasks in this phase are logged:**
+
+```
+Phase {N}: {Phase Name} — complete ({M} tasks logged).
+```
+
+→ Return to **Step 5** for the next phase.
+
+**If all phases are complete:** → Proceed to **Step 7**.

package/skills/technical-planning/references/steps/define-phases.md

@@ -0,0 +1,40 @@
+# Define Phases
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+Load **[phase-design.md](../phase-design.md)** — the principles for structuring phases as independently valuable, testable increments built on a walking skeleton.
+
+---
+
+Orient the user:
+
+> "I've read the full specification. I'm going to propose a phase structure — how we break this into independently testable stages. Once we agree on the phases, we'll take each one and break it into tasks."
+
+With the full specification understood, break it into logical phases. Understanding what tasks belong in each phase is necessary to determine the right ordering.
+
+Present the proposed phase structure using this format:
+
+```
+Phase {N}: {Phase Name}
+  Goal: {What this phase accomplishes}
+  Why this order: {Why this phase comes at this position in the sequence}
+  Acceptance criteria:
+    - [ ] {First verifiable criterion}
+    - [ ] {Second verifiable criterion}
+```
+
+**STOP.** Present your proposed phase structure and ask:
+
+> **To proceed, choose one:**
+> - **"Approve"** — Phase structure is confirmed. I'll proceed to task breakdown.
+> - **"Adjust"** — Tell me what to change: reorder, split, merge, add, or remove phases.
+
+#### If Adjust
+
+Incorporate feedback, re-present the updated phase structure, and ask again. Repeat until approved.
+
+#### If Approved
+
+→ Proceed to **Step 5**.

package/skills/technical-planning/references/steps/define-tasks.md

@@ -0,0 +1,43 @@
+# Define Tasks
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+Load **[task-design.md](../task-design.md)** — the principles for breaking phases into well-scoped, vertically-sliced tasks.
+
+---
+
+Orient the user:
+
+> "Taking Phase {N}: {Phase Name} and breaking it into tasks. Here's the overview — once we agree on the list, I'll write each task out in full detail."
+
+Take the first (or next) phase and break it into tasks. Present a high-level overview so the user can see the shape of the phase before committing to the detail of each task.
+
+Present the task overview using this format:
+
+```
+Phase {N}: {Phase Name}
+
+  1. {Task Name} — {One-line summary}
+     Edge cases: {comma-separated list, or "none"}
+
+  2. {Task Name} — {One-line summary}
+     Edge cases: {comma-separated list, or "none"}
+```
+
+This overview establishes the scope and ordering. The user should be able to see whether the phase is well-structured, whether tasks are in the right order, and whether anything is missing or unnecessary — before investing time in writing out full task detail.
+
+**STOP.** Present the phase task overview and ask:
+
+> **To proceed, choose one:**
+> - **"Approve"** — Task list is confirmed. I'll begin writing full task detail.
+> - **"Adjust"** — Tell me what to change: reorder, split, merge, add, or remove tasks.
+
+#### If Adjust
+
+Incorporate feedback, re-present the updated task overview, and ask again. Repeat until approved.
+
+#### If Approved
+
+→ Proceed to **Step 6**.

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.