@leeovery/claude-technical-workflows 2.0.21 → 2.0.23

package/package.json

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

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

@@ -15,7 +15,7 @@ This is a single file per topic.
 ```markdown
 # Discussion: {Topic}
 
-**Date**: YYYY-MM-DD
+**Date**: YYYY-MM-DD *(use today's actual date)*
 **Status**: Exploring | Deciding | Concluded
 
 ## Context

package/skills/technical-planning/references/output-backlog-md.md

@@ -59,7 +59,7 @@ project: {TOPIC_NAME}
 # Plan Reference: {Topic Name}
 
 **Specification**: `docs/workflow/specification/{topic}.md`
-**Created**: {DATE}
+**Created**: YYYY-MM-DD *(use today's actual date)*
 
 ## About This Plan
 

package/skills/technical-planning/references/output-beads.md

@@ -246,7 +246,7 @@ epic: bd-{EPIC_ID}
 # Plan Reference: {Topic Name}
 
 **Specification**: `docs/workflow/specification/{topic}.md`
-**Created**: {DATE}
+**Created**: YYYY-MM-DD *(use today's actual date)*
 
 ## About This Plan
 

package/skills/technical-planning/references/output-linear.md

@@ -156,7 +156,7 @@ team: {TEAM_NAME}
 # Plan Reference: {Topic Name}
 
 **Specification**: `docs/workflow/specification/{topic}.md`
-**Created**: {DATE}
+**Created**: YYYY-MM-DD *(use today's actual date)*
 
 ## About This Plan
 

package/skills/technical-planning/references/output-local-markdown.md

@@ -38,7 +38,7 @@ format: local-markdown
 
 # Implementation Plan: {Feature/Project Name}
 
-**Date**: YYYY-MM-DD
+**Date**: YYYY-MM-DD *(use today's actual date)*
 **Status**: Draft | Ready | In Progress | Completed
 **Specification**: `docs/workflow/specification/{topic}.md`
 
@@ -145,7 +145,7 @@ Triggers and steps
 
 | Date | Change |
 |------|--------|
-| YYYY-MM-DD | Created from specification |
+| YYYY-MM-DD *(use today's actual date)* | Created from specification |
 ```
 
 ## Cross-Topic Dependencies

package/skills/technical-specification/SKILL.md

@@ -48,6 +48,8 @@ Either way: Transform unvalidated reference material into a specification that's
 
 5. **Log**: Only when approved, write content verbatim to the specification.
 
+6. **Final review**: After all topics and dependencies are documented, perform a comprehensive review of ALL source material against the specification. Flag any potentially missed content to the user - but only from the sources, never fabricated. User confirms before any additions.
+
 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 source material.
 
 ## Critical Rules

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

@@ -104,7 +104,7 @@ Suggested skeleton:
 # Specification: [Topic Name]
 
 **Status**: Building specification
-**Last Updated**: [timestamp]
+**Last Updated**: YYYY-MM-DD *(use today's actual date)*
 
 ---
 
@@ -139,52 +139,160 @@ If working notes exist, they show where you left off.
 
 ## Dependencies Section
 
-At the end of every specification, add a **Dependencies** section that identifies what other parts of the system need to exist before implementation.
+At the end of every specification, add a **Dependencies** section that identifies **prerequisites** - systems that must exist before this feature can be built.
 
 The same workflow applies: present the dependencies section for approval, then log verbatim when approved.
 
+### What Dependencies Are
+
+Dependencies are **blockers** - things that must exist before implementation can begin.
+
+Think of it like building a house: if you're specifying the roof, the walls are a dependency. You cannot build a roof without walls to support it. The walls must exist first.
+
+**The test**: "If system X doesn't exist, can we still build this feature?"
+- If **no** → X is a dependency
+- If **yes** → X is not a dependency (even if the systems work together)
+
+### What Dependencies Are NOT
+
+**Do not list systems just because they:**
+- Work together with this feature
+- Share data or communicate with this feature
+- Are related or in the same domain
+- Would be nice to have alongside this feature
+
+Two systems that cooperate are not necessarily dependent. A notification system and a user preferences system might work together (preferences control notification settings), but if you can build the notification system with hardcoded defaults and add preference integration later, then preferences are not a dependency.
+
 ### How to Identify Dependencies
 
-Review the specification for references to:
-- Other systems or features (e.g., "triggers when order is placed" → Order system dependency)
-- Data models from other domains (e.g., "FK to users" → User model must exist)
-- UI or configuration in other systems (e.g., "configured in admin dashboard" → Dashboard dependency)
-- Events or state from other systems (e.g., "listens for payment.completed" → Payment system dependency)
+Review the specification for cases where implementation is **literally blocked** without another system:
+
+- **Data that must exist first** (e.g., "FK to users" → User model must exist, you can't create the FK otherwise)
+- **Events you consume** (e.g., "listens for payment.completed" → Payment system must emit this event)
+- **APIs you call** (e.g., "fetches inventory levels" → Inventory API must exist)
+- **Infrastructure requirements** (e.g., "stores files in S3" → S3 bucket configuration must exist)
+
+**Do not include** systems where you merely reference their concepts or where integration could be deferred.
 
 ### Categorization
 
-**Required**: Cannot proceed without this. Core functionality depends on it.
+**Required**: Implementation cannot start without this. The code literally cannot be written.
 
-**Partial Requirement**: Only specific elements are needed, not the full system. Note the minimum scope.
+**Partial Requirement**: Only specific elements are needed, not the full system. Note the minimum scope that unblocks implementation.
 
 ### Format
 
 ## Dependencies
 
-Systems referenced in this specification that need to exist before implementation:
+Prerequisites that must exist before implementation can begin:
 
 ### Required
 
-| Dependency | Why Needed | Blocking Elements |
-|------------|------------|-------------------|
-| **[System Name]** | [Brief explanation of why] | [What parts of this spec are blocked] |
+| Dependency | Why Blocked | What's Unblocked When It Exists |
+|------------|-------------|--------------------------------|
+| **[System Name]** | [Why implementation literally cannot proceed] | [What parts of this spec can then be built] |
 
 ### Partial Requirement
 
-| Dependency | Why Needed | Minimum Scope |
-|------------|------------|---------------|
-| **[System Name]** | [Brief explanation] | [What subset is actually needed] |
+| Dependency | Why Blocked | Minimum Scope Needed |
+|------------|-------------|---------------------|
+| **[System Name]** | [Why implementation cannot proceed] | [Specific subset that unblocks us] |
 
 ### Notes
 
-- [Any clarifications about what can be built independently]
-- [Workarounds or alternatives if dependencies don't exist yet]
+- [What can be built independently, without waiting]
+- [Workarounds if dependencies don't exist yet]
 
 ### Purpose
 
 This section feeds into the planning phase, where dependencies become blocking relationships between epics/phases. It helps sequence implementation correctly.
 
-Analyze the specification in isolation - identify what it references that must exist, not what you know exists elsewhere in the project.
+**Key distinction**: This is about sequencing what must come first, not mapping out what works together. A feature may integrate with many systems - only list the ones that block you from starting.
+
+## Final Specification Review
+
+After documenting dependencies, perform a **final comprehensive review** of the entire specification against all source material. This is your last chance to catch anything that was missed.
+
+**Why this matters**: The specification is the golden document. Plans are built from it. If a detail isn't in the specification, it won't be built - regardless of whether it was in the source material.
+
+### The Review Process
+
+1. **Re-read ALL source material** - Go back to every source document, discussion, research note, and reference. Don't rely on memory.
+
+2. **Compare systematically** - For each piece of source material:
+   - What topics does it cover?
+   - Are those topics fully captured in the specification?
+   - Are there details, edge cases, or decisions that didn't make it?
+
+3. **Search for the forgotten** - Look specifically for:
+   - Edge cases mentioned in passing
+   - Constraints or requirements buried in tangential discussions
+   - Technical details that seemed minor at the time
+   - Decisions made early that may have been overshadowed
+   - Error handling, validation rules, or boundary conditions
+   - Integration points or data flows mentioned but not elaborated
+
+4. **Flag what you find** - When you discover potentially missed content, present it to the user. There are two cases:
+
+   **Enhancing an existing topic** - Details that belong in an already-documented section:
+
+   > "During my final review, I found additional detail about [existing topic] that isn't captured. From [source]:
+   >
+   > [quote or summary from source material]
+   >
+   > I'd add this to the [section name] section. Would you like me to include it, or show you the full section with this addition first?"
+
+   If the user wants to see context, present the entire section with the new content clearly marked (e.g., with a comment like `<!-- NEW -->` or by calling it out before the block).
+
+   **An entirely missed topic** - Something that warrants its own section but was glossed over:
+
+   > "During my final review, I found [topic] discussed in [source] that doesn't have coverage in the specification:
+   >
+   > [quote or summary from source material]
+   >
+   > This would be a new section. Should I add it?"
+
+   In both cases, you know where the content belongs - existing topics get enhanced in place, new topics get added at the end.
+
+5. **Never fabricate** - Every item you flag must trace back to specific source material. If you can't point to where it came from, don't suggest it. The goal is to catch missed content, not invent new requirements.
+
+6. **User confirms before inclusion** - Standard workflow applies: present proposed additions, get approval, then log verbatim.
+
+7. **Surface potential gaps** - After reviewing source material, consider whether the specification has gaps that the sources simply didn't address. These might be:
+   - Edge cases that weren't discussed
+   - Error scenarios not covered
+   - Integration points that seem implicit but aren't specified
+   - Behaviors that are ambiguous without clarification
+
+   Present these as a batch for the user to triage:
+
+   > "I've identified some potential gaps that aren't covered in the source material:
+   >
+   > 1. **[Gap A]** - [brief description of what's unclear/missing]
+   > 2. **[Gap B]** - [brief description]
+   > 3. **[Gap C]** - [brief description]
+   >
+   > Are any of these areas you'd like to discuss, or are they intentionally out of scope?"
+
+   The user can then pick which gaps (if any) need addressing. For those they want to discuss, work through them and add to the specification with standard approval workflow.
+
+   This should be infrequent - most gaps will be caught from source material. But occasionally the sources themselves have blind spots worth surfacing.
+
+### What You're NOT Doing
+
+- **Not inventing requirements** - When surfacing gaps not in sources, you're asking questions, not proposing answers
+- **Not assuming gaps need filling** - If something isn't in the sources, it may have been intentionally omitted
+- **Not padding the spec** - Only add what's genuinely missing and relevant
+- **Not re-litigating decisions** - If something was discussed and rejected, it stays rejected
+
+### Completing the Review
+
+When you've:
+- Systematically reviewed all source material for missed content
+- Addressed any discovered gaps with the user
+- Surfaced any potential gaps not covered by sources (and resolved them)
+
+...then inform the user the final review is complete and proceed to getting sign-off on the specification.
 
 ## Completion