@leeovery/claude-technical-workflows 2.0.44 → 2.0.46

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-specification/references/specification-guide.md

@@ -148,6 +148,11 @@ topic: {topic-name}
 status: in-progress
 type: feature
 date: YYYY-MM-DD  # Use today's actual date
+sources:
+  - name: discussion-one
+    status: incorporated
+  - name: discussion-two
+    status: pending
 ---
 
 # Specification: [Topic Name]
@@ -169,6 +174,45 @@ date: YYYY-MM-DD  # Use today's actual date
 - **status**: `in-progress` (building) or `concluded` (complete)
 - **type**: `feature` (something to build) or `cross-cutting` (patterns/policies)
 - **date**: Last updated date
+- **sources**: Array of source discussions with incorporation status (see below)
+
+### Sources and Incorporation Status
+
+**All specifications must track their sources**, even when built from a single discussion. This enables proper tracking when additional discussions are later added to the same grouping.
+
+When a specification is built from discussion(s), track each source with its incorporation status:
+
+```yaml
+sources:
+  - name: auth-flow
+    status: incorporated
+  - name: api-design
+    status: pending
+```
+
+**Status values:**
+- `pending` - Source has been selected for this specification but content extraction is not complete
+- `incorporated` - Source content has been fully extracted and woven into the specification
+
+**When to update source status:**
+
+1. **When creating the specification**: All sources start as `pending`
+2. **After completing exhaustive extraction from a source**: Mark that source as `incorporated`
+3. **When adding a new source to an existing spec**: Add it with `status: pending`
+
+**How to determine if a source is incorporated:**
+
+A source is `incorporated` when you have:
+- Performed exhaustive extraction (reviewed ALL content in the source for relevant material)
+- Presented and logged all relevant content from that source
+- No more content from that source needs to be extracted
+
+**Important**: The specification's overall `status: concluded` should only be set when:
+- All sources are marked as `incorporated`
+- Both review phases are complete
+- User has signed off
+
+If a new source is added to a concluded specification (via grouping analysis), the specification effectively needs updating - even if the file still says `status: concluded`, the presence of `pending` sources indicates work remains.
 
 ## Specification Types
 

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.