@leeovery/claude-technical-workflows 2.0.45 → 2.0.47

package/skills/technical-planning/references/phase-design.md

@@ -0,0 +1,146 @@
+# Phase Design
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+This reference defines the principles for breaking specifications into implementation phases. It is loaded when phases are first proposed and stays in context through phase approval.
+
+## What Makes a Good Phase
+
+Each phase should:
+
+- **Deliver a working increment** — not a technical layer, but functionality that can be used or tested end-to-end
+- **Have clear acceptance criteria** — checkboxes that are pass/fail verifiable
+- **Follow natural boundaries** — domain, feature, or capability boundaries, not architectural layers
+- **Leave the system working** — every phase ends with a green test suite and deployable code
+- **Be independently valuable** — if the project stopped after this phase, something useful would exist
+
+---
+
+## The Walking Skeleton
+
+Phase 1 is always a **walking skeleton** — the thinnest possible end-to-end slice that threads through all system layers and proves the architecture works.
+
+The walking skeleton:
+
+- Touches every architectural component the system needs (database, API, UI, external services)
+- Delivers one complete flow, however minimal
+- Establishes the patterns subsequent phases will follow
+- Is production code, not throwaway — it becomes the foundation
+
+**Example** (Slack clone):
+
+> Phase 1: "Any unauthenticated person can post messages in a hardcoded #general room. Messages persist through page refreshes."
+>
+> No auth, no accounts, no multiple rooms. Just the thinnest thread through the entire stack.
+
+**Example** (Calendar app):
+
+> Phase 1: "A single event can be created with title, start, and end time, persisted, and retrieved by ID."
+>
+> No recurrence, no sharing, no notifications. Just one thing working end-to-end.
+
+The skeleton validates architecture assumptions at the cheapest possible moment. If the end-to-end flow doesn't work, you discover it in Phase 1 — not after building three phases of isolated components.
+
+This is the **steel thread** principle: never have big-bang integration. By threading through all layers immediately, integration is the first thing you solve, not the last.
+
+---
+
+## Vertical Phases
+
+After the walking skeleton, each subsequent phase adds complete functionality — a vertical slice through the relevant layers.
+
+**Vertical (prefer):**
+
+```
+Phase 1: Walking skeleton — single event CRUD, end-to-end
+Phase 2: Recurring events — rules, instance generation, single-instance editing
+Phase 3: Sharing and permissions — invite users, permission levels, shared calendars
+Phase 4: Notifications — email and push notifications for event changes
+```
+
+Each phase delivers something a user or test suite can validate independently.
+
+**Horizontal (avoid):**
+
+```
+Phase 1: All database models and migrations
+Phase 2: All service classes and business logic
+Phase 3: All API endpoints
+Phase 4: All UI components
+Phase 5: Wire everything together
+```
+
+Nothing works until Phase 5. No phase is independently testable. Integration risk concentrates at the end.
+
+A phase may touch multiple architectural layers — that's expected. The test is: **does this phase deliver working functionality, or does it deliver infrastructure that only becomes useful later?**
+
+### Progression
+
+**Skeleton → Core features → Edge cases → Refinement**
+
+- **Skeleton** (Phase 1): Thinnest end-to-end slice proving the architecture
+- **Core features**: Each phase adds a complete capability, building on what exists
+- **Edge cases**: Handling boundary conditions, error scenarios, unusual inputs
+- **Refinement**: Performance optimisation, UX polish, hardening
+
+This ordering means each phase builds on a working system. The skeleton establishes the pattern; core features flesh it out; edge cases harden it; refinement polishes it.
+
+---
+
+## Phase Boundaries
+
+A phase boundary belongs where:
+
+- **A meaningful state change occurs** — the system gains a new capability
+- **Human validation is needed** — the approach should be confirmed before building more
+- **The risk profile shifts** — different concerns, different complexity, different unknowns
+- **The work's nature changes** — from core functionality to edge cases, from features to optimisation
+
+### When to split
+
+- The combined work exceeds what can be reasoned about in a single focused session
+- An intermediate state is independently valuable or testable
+- You need a checkpoint to validate before investing further
+- Different parts have different risk or uncertainty levels
+
+### When to keep together
+
+- High cohesion — changes to one part directly affect the other
+- The intermediate state has no independent value
+- Splitting would create phases that aren't meaningful milestones
+- The overhead of phase management exceeds the benefit
+
+### Granularity check
+
+If a phase has only 1-2 trivial tasks, it's probably too thin — merge it. If a phase has 8+ tasks spanning multiple concerns, it's probably too thick — split it. Most phases land at 3-6 focused tasks.
+
+---
+
+## Cross-Phase Coupling
+
+**Maximize cohesion within a phase, minimize dependencies between phases.**
+
+A well-bounded phase could theoretically be reordered or dropped without cascading failures across other phases. In practice, phases have a natural sequence (the skeleton must come first), but each phase should be as self-contained as possible.
+
+Strategies:
+
+- **Walking skeleton first** — subsequent phases add to a working system rather than depending on future phases
+- **Clear interfaces between phases** — each phase produces defined contracts (API shapes, data models, test suites) that subsequent phases consume
+- **Shared infrastructure in Phase 1** — if multiple phases need the same foundation, it belongs in the skeleton
+- **No forward references** — a phase should never depend on something that hasn't been built yet
+
+---
+
+## Anti-Patterns
+
+**Horizontal phases** — organising by technical layer ("all models, then all services, then all controllers"). Defers integration risk, produces phases that aren't independently valuable. The walking skeleton eliminates this by integrating from the start.
+
+**God phase** — one massive phase covering too many concerns. Results in unclear success criteria, inability to track progress, and cognitive overload. If you can't summarise a phase's goal in one sentence, it needs splitting.
+
+**Trivial phases** — phases so small they're just individual tasks wearing a trenchcoat. Phase management has overhead; don't pay it for work that doesn't warrant a checkpoint.
+
+**Infrastructure-only phases** (after Phase 1) — phases that deliver tooling, configuration, or refactoring with no user-facing value. These should be folded into the phase that needs them, unless they're genuinely cross-cutting prerequisites.
+
+**Speculative phases** — phases planned for hypothetical future requirements. Plan what the specification defines, not what might be needed later.

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**.