@leeovery/claude-technical-workflows 2.0.45 → 2.0.46

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.

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

@@ -0,0 +1,158 @@
+# Task Design
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+This reference defines the principles for breaking phases into tasks and writing task detail. It is loaded when tasks are first proposed and stays in context through task detailing.
+
+## One Task = One TDD Cycle
+
+Write test → implement → pass → commit. Each task produces a single, verifiable increment.
+
+---
+
+## Cross-Cutting References
+
+Cross-cutting specifications (e.g., caching strategy, error handling conventions, rate limiting policy) are not things to build — they are architectural decisions that influence how features are built. They inform technical choices within the plan without adding scope.
+
+If cross-cutting specifications were provided alongside the specification:
+
+1. **Apply their decisions** when designing tasks (e.g., if caching strategy says "cache API responses for 5 minutes", reflect that in relevant task detail)
+2. **Note where patterns apply** — when a task implements a cross-cutting pattern, reference it
+3. **Include a "Cross-Cutting References" section** in the plan linking to these specifications
+
+Cross-cutting references are context, not scope. They shape how tasks are written, not what tasks exist.
+
+---
+
+## Vertical Slicing
+
+Prefer **vertical slices** that deliver complete, testable functionality over horizontal slices that separate by technical layer.
+
+**Horizontal (avoid)**:
+
+```
+Task 1: Create all database models
+Task 2: Create all service classes
+Task 3: Wire up integrations
+Task 4: Add error handling
+```
+
+Nothing works until Task 4. No task is independently verifiable.
+
+**Vertical (prefer)**:
+
+```
+Task 1: Fetch and store events from provider (happy path)
+Task 2: Handle pagination for large result sets
+Task 3: Handle authentication token refresh
+Task 4: Handle rate limiting
+```
+
+Each task delivers a complete slice of functionality that can be tested in isolation.
+
+Within a bounded feature, vertical slicing means each task completes a coherent unit of that feature's functionality — not that it must touch UI/API/database layers. The test is: *can this task be verified independently?*
+
+TDD naturally encourages vertical slicing — when you think "what test can I write?", you frame work as complete, verifiable behaviour rather than technical layers.
+
+---
+
+## Task Ordering
+
+Within a phase, order tasks by:
+
+1. **Foundation / setup** — models, migrations, base configuration needed by other tasks
+2. **Happy path** — the primary expected behaviour, end-to-end
+3. **Error handling** — validation failures, API errors, permission checks
+4. **Edge cases** — boundary conditions, unusual inputs, race conditions
+
+This ordering means the first tasks establish the pattern and the later tasks extend it. Each task builds on a working foundation rather than building in the dark.
+
+**Edge cases as separate tasks**: Keep the happy-path task focused. If a task's acceptance criteria start growing beyond 3-4 items, the edge cases probably deserve their own tasks. This keeps each TDD cycle tight and each task independently verifiable.
+
+---
+
+## Scope Signals
+
+### Too big
+
+A task is probably too big if:
+
+- The "Do" section exceeds 5 concrete steps
+- You can't describe the test in one sentence
+- It touches more than one architectural boundary (e.g., both API endpoint and queue worker)
+- Completion requires multiple distinct behaviours to be implemented
+
+Split it. Two focused tasks are better than one sprawling task.
+
+### Too small
+
+A task is probably too small if:
+
+- It's a single line change with no meaningful test
+- It's mechanical housekeeping (renaming, moving files) that doesn't warrant its own TDD cycle
+- It only makes sense as a step within another task
+
+Merge it into the task that needs it.
+
+### The independence test
+
+Ask: "Can I write a test for this task that passes without any other task being complete (within this phase)?" If yes, it's well-scoped. If no, it might need to be merged with its dependency or reordered.
+
+---
+
+## Task Template
+
+Every task should follow this structure:
+
+```markdown
+### Task N: [Clear action statement]
+
+**Problem**: Why this task exists — what issue or gap it addresses.
+
+**Solution**: What we're building — the high-level approach.
+
+**Outcome**: What success looks like — the verifiable end state.
+
+**Do**:
+- Specific implementation steps
+- File locations and method names where helpful
+- Concrete guidance, not vague directions
+
+**Acceptance Criteria**:
+- [ ] First verifiable criterion
+- [ ] Second verifiable criterion
+- [ ] Edge case handling criterion
+
+**Tests**:
+- `"it does the primary expected behaviour"`
+- `"it handles edge case correctly"`
+- `"it fails appropriately for invalid input"`
+
+**Context**: (when relevant)
+> Relevant details from specification: code examples, architectural decisions,
+> data models, or constraints that inform implementation.
+```
+
+### Field Requirements
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| Problem | Yes | One sentence minimum — why this task exists |
+| Solution | Yes | One sentence minimum — what we're building |
+| Outcome | Yes | One sentence minimum — what success looks like |
+| Do | Yes | At least one concrete action |
+| Acceptance Criteria | Yes | At least one pass/fail criterion |
+| Tests | Yes | At least one test name; include edge cases, not just happy path |
+| Context | When relevant | Only include when spec has details worth pulling forward |
+
+### The Template as Quality Gate
+
+If you struggle to articulate a clear Problem for a task, this signals the task may be:
+
+- **Too granular**: Merge with a related task
+- **Mechanical housekeeping**: Include as a step within another task
+- **Poorly understood**: Revisit the specification
+
+Every standalone task should have a reason to exist that can be stated simply. The template enforces this — difficulty completing it is diagnostic information, not a problem to work around.

package/skills/technical-research/SKILL.md

@@ -20,7 +20,13 @@ Either way: Explore feasibility (technical, business, market), validate assumpti
 - **Topic or idea** (required) - What to research/explore
 - **Existing context** (optional) - Any prior research or constraints
 
-**If missing:** Will ask user what they want to explore.
+**Before proceeding**, confirm the required input is clear. If anything is missing or unclear, **STOP** and resolve with the user.
+
+- **No topic provided?**
+  > "What would you like to research or explore? This could be a new idea, a technical concept, a market opportunity — anything you want to investigate."
+
+- **Topic is vague or could go many directions?**
+  > "You mentioned {topic}. That could cover a lot of ground — is there a specific angle you'd like to start with, or should I explore broadly?"
 
 ## Your Expertise
 
@@ -87,6 +93,8 @@ Research without documentation is wasted. Follow this loop:
 
 ## Critical Rules
 
+**No status field**: Research documents do NOT have a `status` field in their frontmatter. Only `topic` and `date`. Research is open-ended by nature — it doesn't "conclude." Even when a research exploration feels complete, do not add `status: concluded` or any similar field. The document stays as-is.
+
 **Don't hallucinate**: Only document what was actually discussed.
 
 **Don't expand**: Capture what was said, don't embellish.

package/skills/technical-research/references/template.md

@@ -30,6 +30,7 @@ What we know so far:
 
 - `topic`: Use `exploration` for the initial exploration file. Use semantic names (`market-landscape`, `technical-feasibility`) when splitting into focused files.
 - `date`: Today's date when creating the document.
+- **No `status` field**: Research documents intentionally have no status. Do not add `status`, `state`, or any lifecycle field. Research is open-ended — it never "concludes."
 
 ## Notes
 

package/skills/technical-review/SKILL.md

@@ -31,7 +31,15 @@ Either way: Verify every plan task was implemented, tested adequately, and meets
 - **Specification content** (optional) - Context for design decisions
 - **Implementation scope** (optional) - What code/files to review. Will identify from git if not specified.
 
-**If missing:** Will ask user for plan location. Can proceed without specification.
+**Before proceeding**, verify the required input is available. If anything is missing, **STOP** — do not proceed until resolved.
+
+- **No plan provided?**
+  > "I need the implementation plan to review against. Could you point me to the plan file (e.g., `docs/workflow/planning/{topic}.md`)?"
+
+- **Plan references a specification that can't be found?**
+  > "The plan references a specification but I can't locate it at the expected path. Could you confirm where the specification is? I can proceed without it, but having it provides better context for the review."
+
+The specification is optional — the review can proceed with just the plan.
 
 ## Review Approach
 

package/skills/technical-specification/SKILL.md

@@ -26,7 +26,16 @@ Either way: Transform unvalidated reference material into a specification that's
   - Any other reference material
 - **Topic name** (required) - Used for the output filename
 
-**If missing:** Will ask user to provide context or point to source files.
+**Before proceeding**, verify all required inputs are available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
+
+- **No source material provided?**
+  > "I need source material to build a specification from. Could you point me to the source files (e.g., `docs/workflow/discussion/{topic}.md`), or provide the content directly?"
+
+- **No topic name provided?**
+  > "What should the specification be named? This determines the output file: `docs/workflow/specification/{name}.md`."
+
+- **Source material seems incomplete or unclear?**
+  > "I have the source material, but {concern}. Should I proceed as-is, or is there additional material I should review?"
 
 **Multiple sources:** When multiple sources are provided, extract exhaustively from ALL of them. Content may be scattered across sources - a decision in one may have constraints or details in another. The specification consolidates everything into a single standalone document.
 

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

@@ -1,235 +0,0 @@
-# Formal Planning
-
-*Reference for **[technical-planning](../SKILL.md)***
-
----
-
-You are creating the formal implementation plan from the specification.
-
-## Before You Begin
-
-**Confirm output format with user.** Ask which format they want, then load the appropriate output adapter from the main skill file. If you don't know which format, ask.
-
-## Planning is Collaborative
-
-Planning is an iterative process between you and the user. The specification contains validated, considered decisions - planning translates that work into actionable structure. But translation still requires judgment, and the user should guide that judgment.
-
-**Stop, reflect, 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
-
-**Never invent to fill gaps.** If the specification doesn't address something, use `[needs-info]` and ask the user. The specification is the golden document - everything in the plan must trace back to it.
-
-**The user expects collaboration.** Planning doesn't have to be done by the agent alone. It's normal and encouraged to pause for guidance rather than guess.
-
-## The Planning Process
-
-### 1. Read Specification
-
-From the specification (`docs/workflow/specification/{topic}.md`), extract:
-- Key decisions and rationale
-- Architectural choices
-- Edge cases identified
-- Constraints and requirements
-- **External dependencies** (from the Dependencies section)
-
-**The specification is your sole input.** Prior source materials have already been validated, filtered, and enriched into the specification. Everything you need is in the specification - do not reference other documents.
-
-#### Extract External Dependencies
-
-The specification's Dependencies section lists things this feature needs from other topics/systems. These are **external dependencies** - things outside this plan's scope that must exist for implementation to proceed.
-
-Copy these into the plan index file (see "External Dependencies Section" below). During planning:
-
-1. **Check for existing plans**: For each dependency, search `docs/workflow/planning/` for a matching topic
-2. **If plan exists**: Try to identify specific tasks that satisfy the dependency. Query the output format to find relevant tasks. If ambiguous, ask the user which tasks apply.
-3. **If no plan exists**: Record the dependency in natural language - it will be linked later via `/link-dependencies` or when that topic is planned.
-
-**Optional reverse check**: Ask the user: "Would you like me to check if any existing plans depend on this topic?"
-
-If yes:
-1. Scan other plan indexes for External Dependencies that reference this topic
-2. For each match, identify which task(s) in the current plan satisfy that dependency
-3. Update the other plan's dependency entry with the task ID (unresolved → resolved)
-
-Alternatively, the user can run `/link-dependencies` later to resolve dependencies across all plans in bulk.
-
-### 2. Define Phases
-
-Break into logical phases:
-- Each independently testable
-- Each has acceptance criteria
-- Progression: Foundation → Core → Edge cases → Refinement
-
-### 3. Break Phases into Tasks
-
-Each task is one TDD cycle:
-- One clear thing to build
-- One test to prove it works
-
-### 4. Write Micro Acceptance
-
-For each task, name the test that proves completion. Implementation writes this test first.
-
-### 5. Address Every Edge Case
-
-Extract each edge case, create a task with micro acceptance.
-
-### 6. Add Code Examples (if needed)
-
-Only for novel patterns not obvious to implement.
-
-### 7. Review Against Specification
-
-Verify:
-- All decisions referenced
-- All edge cases have tasks
-- Each phase has acceptance criteria
-- Each task has micro acceptance
-
-## Phase Design
-
-**Each phase should**:
-- Be independently testable
-- Have clear acceptance criteria (checkboxes)
-- Provide incremental value
-
-**Progression**: Foundation → Core functionality → Edge cases → Refinement
-
-## Task Design
-
-**One task = One TDD cycle**: write test → implement → pass → commit
-
-### Task Structure
-
-Every task should follow this structure:
-
-```markdown
-### Task N: [Clear action statement]
-
-**Problem**: Why this task exists - what issue or gap it addresses.
-
-**Solution**: What we're building - the high-level approach.
-
-**Outcome**: What success looks like - the verifiable end state.
-
-**Do**:
-- Specific implementation steps
-- File locations and method names where helpful
-- Concrete guidance, not vague directions
-
-**Acceptance Criteria**:
-- [ ] First verifiable criterion
-- [ ] Second verifiable criterion
-- [ ] Edge case handling criterion
-
-**Tests**:
-- `"it does the primary expected behavior"`
-- `"it handles edge case correctly"`
-- `"it fails appropriately for invalid input"`
-
-**Context**: (when relevant)
-> Relevant details from specification: code examples, architectural decisions,
-> data models, or constraints that inform implementation.
-```
-
-### Field Requirements
-
-| Field | Required | Notes |
-|-------|----------|-------|
-| Problem | Yes | One sentence minimum - why this task exists |
-| Solution | Yes | One sentence minimum - what we're building |
-| Outcome | Yes | One sentence minimum - what success looks like |
-| Do | Yes | At least one concrete action |
-| Acceptance Criteria | Yes | At least one pass/fail criterion |
-| Tests | Yes | At least one test name; include edge cases, not just happy path |
-| Context | When relevant | Only include when spec has details worth pulling forward |
-
-### The Template as Quality Gate
-
-If you struggle to articulate a clear Problem for a task, this signals the task may be:
-
-- **Too granular**: Merge with a related task
-- **Mechanical housekeeping**: Include as a step within another task
-- **Poorly understood**: Revisit the specification
-
-Every standalone task should have a reason to exist that can be stated simply. The template enforces this - difficulty completing it is diagnostic information, not a problem to work around.
-
-### Vertical Slicing
-
-Prefer **vertical slices** that deliver complete, testable functionality over horizontal slices that separate by technical layer.
-
-**Horizontal (avoid)**:
-```
-Task 1: Create all database models
-Task 2: Create all service classes
-Task 3: Wire up integrations
-Task 4: Add error handling
-```
-
-Nothing works until Task 4. No task is independently verifiable.
-
-**Vertical (prefer)**:
-```
-Task 1: Fetch and store events from provider (happy path)
-Task 2: Handle pagination for large result sets
-Task 3: Handle authentication token refresh
-Task 4: Handle rate limiting
-```
-
-Each task delivers a complete slice of functionality that can be tested in isolation.
-
-Within a bounded feature, vertical slicing means each task completes a coherent unit of that feature's functionality - not that it must touch UI/API/database layers. The test is: *can this task be verified independently?*
-
-TDD naturally encourages vertical slicing - when you think "what test can I write?", you frame work as complete, verifiable behavior rather than technical layers
-
-## 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
-
-## Flagging Incomplete Tasks
-
-When information is missing, mark it clearly with `[needs-info]`:
-
-```markdown
-### Task 3: Configure rate limiting [needs-info]
-
-**Do**: Set up rate limiting for the API endpoint
-**Test**: `it throttles requests exceeding limit`
-
-**Needs clarification**:
-- What's the rate limit threshold?
-- Per-user or per-IP?
-```
-
-Planning is iterative. Create structure, flag gaps, refine.
-
-## Quality Checklist
-
-Before handing off to implementation:
-
-- [ ] Clear phases with acceptance criteria
-- [ ] Each phase has TDD-sized tasks
-- [ ] Each task has micro acceptance (test name)
-- [ ] All edge cases mapped to tasks
-- [ ] Gaps flagged with `[needs-info]`
-- [ ] External dependencies documented in plan index
-
-## External Dependencies Section
-
-The plan index file must include an External Dependencies section. See **[dependencies.md](dependencies.md)** for the format, states, and how they affect implementation.
-
-## Commit Frequently
-
-Commit planning docs at natural breaks, after significant progress, and before any context refresh.
-
-Context refresh = memory loss. Uncommitted work = lost work.
-
-## Output
-
-Load the appropriate output adapter (linked from the main skill file) for format-specific structure and templates.