@leeovery/claude-technical-workflows 2.0.17 → 2.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.0.17",
+  "version": "2.0.19",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/technical-planning/SKILL.md

@@ -43,6 +43,8 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 
 **Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work.
 
-**Never invent reasoning**: If it's not in the specification, ask again.
+**Never invent reasoning**: If it's not in the specification, ask again. The specification is the golden document - all plan content must trace back to it.
 
 **Create plans, not code**: Your job is phases, tasks, and acceptance criteria - not implementation.
+
+**Collaborate with the user**: Planning is iterative. Stop and ask when the specification is ambiguous, multiple valid approaches exist, or you're uncertain about task scope. The user expects collaboration - don't guess when you can ask.

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

@@ -10,6 +10,20 @@ You are creating the formal implementation plan from the specification.
 
 **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
@@ -86,13 +100,91 @@ Verify:
 
 ## Task Design
 
-**Each task should**:
-- Be a single TDD cycle
-- Have micro acceptance (specific test name)
-- Do one clear thing
-
 **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.

package/skills/technical-specification/SKILL.md

@@ -37,15 +37,17 @@ Either way: Transform unvalidated reference material into a specification that's
 
 ## What You Do
 
-1. **Filter**: Reference material may contain hallucinations, inaccuracies, or outdated concepts. Validate before including.
+1. **Extract exhaustively**: For each topic, re-scan ALL source material. Search for keywords and related terms. Information is often scattered - collect it all before synthesizing. Include only what we're building (not discarded alternatives).
 
-2. **Enrich**: Reference material may have gaps. Fill them through discussion.
+2. **Filter**: Reference material may contain hallucinations, inaccuracies, or outdated concepts. Validate before including.
 
-3. **Present**: Synthesize and present content to the user in the format it would appear in the specification.
+3. **Enrich**: Reference material may have gaps. Fill them through discussion.
 
-4. **Log**: Only when approved, write content verbatim to the specification.
+4. **Present**: Synthesize and present content to the user in the format it would appear in the specification.
 
-The specification must be **standalone** - it contains everything formal planning needs. No references back to discussions or other source material.
+5. **Log**: Only when approved, write content verbatim to the specification.
+
+The specification is the **golden document** - planning uses only this. If information doesn't make it into the specification, it won't be built. No references back to discussions or other source material.
 
 ## Critical Rules
 

package/skills/technical-specification/references/specification-guide.md

@@ -33,8 +33,31 @@ Before starting any topic, identify ALL available reference material:
 
 Work through the specification **topic by topic**:
 
-### 1. Review
-Read all reference material for the current topic. Understand what exists.
+### 1. Review (Exhaustive Extraction)
+
+**This step is critical. The specification is the golden document - if information doesn't make it here, it won't be built.**
+
+For each topic or subtopic, perform exhaustive extraction:
+
+1. **Re-scan ALL source material** - Don't rely on memory. Go back to the source material and systematically review it for the current topic.
+
+2. **Search for keywords** - Topics are rarely contained in one section. Search for:
+   - The topic name and synonyms
+   - Related concepts and terms
+   - Names of systems, fields, or behaviors mentioned in context
+
+3. **Collect scattered information** - Source material (research, discussions, requirements) is often non-linear. Information about a single topic may be scattered across:
+   - Multiple sections of the same document
+   - Different documents entirely
+   - Tangential discussions that revealed important details
+
+4. **Filter for what we're building** - Include only validated decisions:
+   - Exclude discarded alternatives
+   - Exclude ideas that were explored but rejected
+   - Exclude "maybes" that weren't confirmed
+   - Include only what the user has decided to build
+
+**Why this matters:** The specification is the single source of truth for planning. Planning will not reference discussions or research - only this document. Missing a detail here means that detail doesn't get implemented.
 
 ### 2. Synthesize and Present
 Present your understanding to the user **in the format it would appear in the specification**:
@@ -98,6 +121,8 @@ Suggested skeleton:
 
 ## Critical Rules
 
+**Exhaustive extraction is non-negotiable**: Before presenting any topic, re-scan source material. Search for keywords. Collect scattered information. The specification is the golden document - planning uses only this. If you miss something, it doesn't get built.
+
 **Present before logging**: Never write content to the specification until the user has seen and approved it.
 
 **Log verbatim**: When approved, write exactly what was presented - no silent modifications.