@leeovery/claude-technical-workflows 2.0.0

package/skills/technical-review/references/review-checklist.md

@@ -0,0 +1,155 @@
+# Review Checklist
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+## Before Starting
+
+1. Read plan: `docs/workflow/planning/{topic}.md`
+2. Read specification: `docs/workflow/specification/{topic}.md` (for context)
+3. Identify what code/files were changed
+4. Check for project-specific skills in `.claude/skills/`
+
+## Task-Based Review (Primary Approach)
+
+Review **every task** in the plan. Don't sample - verify all of them.
+
+### Extract All Tasks
+
+From the plan, list every task across all phases:
+- Note each task's description
+- Note each task's acceptance criteria
+- Note expected micro acceptance (test name)
+
+### Parallel Verification
+
+Spawn `chain-verifier` subagents **in parallel** for ALL tasks:
+
+```
+Task 1 ──▶ [chain-verifier] ──▶ Findings
+Task 2 ──▶ [chain-verifier] ──▶ Findings
+Task 3 ──▶ [chain-verifier] ──▶ Findings  (all running in parallel)
+Task 4 ──▶ [chain-verifier] ──▶ Findings
+  ...
+Task N ──▶ [chain-verifier] ──▶ Findings
+```
+
+**How to invoke each chain-verifier:**
+
+Provide:
+- The specific task (with acceptance criteria)
+- Path to specification (for context)
+- Path to plan (for phase context)
+- Implementation scope (files/directories changed)
+
+**Each chain-verifier checks:**
+1. Implementation exists and matches acceptance criteria
+2. Tests are adequate (not under-tested, not over-tested)
+3. Code quality is acceptable
+
+**Aggregate the findings:**
+
+Once all chain-verifiers complete, synthesize their reports:
+- Collect all incomplete/failed tasks as blocking issues
+- Collect all test issues (under/over-tested)
+- Collect all code quality concerns
+- Include specific file:line references
+
+## Per-Task Verification Details
+
+For each task, the chain-verifier checks:
+
+### Implementation
+
+- Is the task implemented?
+- Does the implementation match the acceptance criteria?
+- Does it align with spec context (load relevant spec section)?
+- Any drift from what was planned?
+
+### Test Adequacy
+
+**Not under-tested:**
+- Does a test exist for this task?
+- Does the test verify the acceptance criteria?
+- Are edge cases from the spec covered?
+- Would the test fail if the feature broke?
+
+**Not over-tested:**
+- Are tests focused on what matters?
+- No redundant assertions testing the same thing?
+- No unnecessary mocking or setup?
+- Tests aren't testing implementation details instead of behavior?
+
+### Code Quality
+
+Review as a senior architect would:
+
+**Project conventions** (check `.claude/skills/` for project-specific guidance):
+- Framework and architecture guidelines defined for the project
+- Code style and patterns specific to the codebase
+
+**General principles** (always apply):
+- **SOLID**: Single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion
+- **DRY**: No unnecessary duplication (without premature abstraction)
+- **Low complexity**: Reasonable cyclomatic complexity, clear code paths
+- **Modern idioms**: Uses current language features appropriately
+- **Readability**: Self-documenting code, clear intent
+- **Security**: No obvious vulnerabilities (injection, exposure, etc.)
+- **Performance**: No obvious inefficiencies (N+1 queries, unnecessary loops, etc.)
+
+## Plan Completion Check
+
+After task-level verification, check overall plan completion:
+
+### Phase Acceptance Criteria
+
+For each phase:
+- Are all phase-level acceptance criteria met?
+- Were all tasks in the phase completed?
+
+### Scope
+
+- Was anything built that wasn't in the plan? (scope creep)
+- Was anything in the plan not built? (missing scope)
+- Any unplanned files or features added?
+
+## Common Issues
+
+**Incomplete task**: Task marked done but not fully implemented
+
+**Under-tested**: Missing tests, or tests don't verify acceptance criteria
+
+**Over-tested**: Redundant tests, testing implementation details, excessive mocking
+
+**Requirement drift**: Implementation doesn't match what was planned
+
+**Missing edge cases**: Spec mentions edge cases not implemented or tested
+
+**Scope creep**: Extra features not in plan
+
+**Orphaned code**: Code added but not used or tested
+
+**Poor readability**: Code works but is hard to understand
+
+## Writing Feedback
+
+Be specific and actionable:
+
+- **Bad**: "Tests need improvement"
+- **Good**: "Test `test_cache_expiry` doesn't verify TTL, only that value is returned"
+
+Reference the plan task:
+
+- **Bad**: "This wasn't done correctly"
+- **Good**: "Plan Phase 2, Task 3 says 'implement Redis cache' with acceptance 'cache stores values for configured TTL' → implementation uses file cache with no TTL. Task incomplete."
+
+Flag test balance issues:
+
+- **Under-tested**: "Task 2.1 has no test for the error case mentioned in spec section 3.2"
+- **Over-tested**: "Task 2.1 has 5 tests that all verify the same happy path with slight variations"
+
+Distinguish blocking vs non-blocking:
+
+- **Blocking**: Incomplete tasks, missing tests, broken functionality
+- **Non-blocking**: Code style suggestions, minor readability improvements

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

@@ -0,0 +1,46 @@
+# Review Template
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+## Template
+
+```markdown
+# Implementation Review: {Topic}
+
+**Verdict**: Approve | Request Changes | Comments Only
+
+## Summary
+[One paragraph overall assessment]
+
+## Specification Compliance
+[Implementation aligns with specification / Note any deviations]
+
+## Plan Completion
+- [ ] Phase 1 acceptance criteria met
+- [ ] Phase 2 acceptance criteria met
+- [ ] All tasks completed
+- [ ] No scope creep
+
+## Code Quality
+[Issues or "No issues found"]
+
+## Test Quality
+[Issues or "Tests adequately verify requirements"]
+
+## Required Changes (if any)
+1. [Specific actionable change]
+2. [Specific actionable change]
+
+## Recommendations (optional)
+[Non-blocking suggestions]
+```
+
+## Verdict Guidelines
+
+**Approve**: All acceptance criteria met, decisions followed, no blocking issues
+
+**Request Changes**: Missing requirements, deviations from decisions, broken functionality, inadequate tests
+
+**Comments Only**: Minor suggestions, style preferences, non-blocking observations

package/skills/technical-specification/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: technical-specification
+description: "Build validated specifications from discussion documents through collaborative refinement. Third phase of research-discussion-specification-plan-implement-review workflow. Use when: (1) User asks to create/build a specification from discussions, (2) User wants to validate and refine discussion content before planning, (3) Converting discussion documents into standalone specifications, (4) User says 'specify this' or 'create a spec' after discussions, (5) Need to filter hallucinations and enrich gaps before formal planning. Creates specifications in docs/workflow/specification/{topic}.md that technical-planning uses to build implementation plans."
+---
+
+# Technical Specification
+
+Act as **expert technical architect** and **specification builder**. Collaborate with the user to transform discussion documents into validated, standalone specifications.
+
+Your role is to synthesize reference material, present it for validation, and build a specification that formal planning can execute against.
+
+## Six-Phase Workflow
+
+1. **Research** (previous): EXPLORE - ideas, feasibility, market, business, learning
+2. **Discussion** (previous): WHAT and WHY - decisions, architecture, edge cases
+3. **Specification** (YOU): REFINE - validate, filter, enrich into standalone spec
+4. **Planning** (next): HOW - phases, tasks, acceptance criteria
+5. **Implementation** (after): DOING - tests first, then code
+6. **Review** (final): VALIDATING - check work against artifacts
+
+You're at step 3. Build the specification. Don't jump to phases, tasks, or code.
+
+## The Process
+
+**Load**: [specification-guide.md](references/specification-guide.md)
+
+**Output**: `docs/workflow/specification/{topic}.md`
+
+**When complete**: User signs off, then proceed to technical-planning.
+
+## What You Do
+
+1. **Filter**: Reference material may contain hallucinations, inaccuracies, or outdated concepts. Validate before including.
+
+2. **Enrich**: Reference material may have gaps. Fill them through discussion.
+
+3. **Present**: Synthesize and present content to the user in the format it would appear in the specification.
+
+4. **Log**: Only when approved, write content verbatim to the specification.
+
+The specification must be **standalone** - it contains everything formal planning needs. No references back to discussions or other source material.
+
+## Critical Rules
+
+**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.
+
+**Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work.
+
+**Trust nothing without validation**: Synthesize and present, but never assume source material is correct.

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

@@ -0,0 +1,170 @@
+# Specification Guide
+
+*Reference for **[technical-specification](../SKILL.md)***
+
+---
+
+You are building a specification - a collaborative workspace where you and the user refine reference material into a validated, standalone document.
+
+## Purpose
+
+Specification building is a **two-way process**:
+
+1. **Filter**: Reference material may contain hallucinations, inaccuracies, or outdated concepts. Validate before including.
+
+2. **Enrich**: Reference material may have gaps. Fill them through discussion.
+
+The specification is the **bridge document** - a workspace for collecting validated, refined content that will feed formal planning.
+
+**The specification must be standalone.** It should contain everything formal planning needs - no references back to discussions or other source material. When complete, it draws a line: formal planning uses only this document.
+
+## Source Materials
+
+Before starting any topic, review ALL available reference material:
+- Discussion documents (from technical-discussion phase)
+- Any existing partial plans
+- Any existing partial specifications
+- Related documentation
+
+**Treat all source material as untrusted input.** Even discussion documents that went through a collaborative process may contain issues. Your job is to synthesize and present - the user validates.
+
+## The Workflow
+
+Work through the specification **topic by topic**:
+
+### 1. Review
+Read all reference material for the current topic. Understand what exists.
+
+### 2. Synthesize and Present
+Present your understanding to the user **in the format it would appear in the specification**:
+
+> "Here's what I understand about [topic] based on the reference material. This is how I'd write it into the specification:
+>
+> [content as it would appear]
+>
+> Does this capture it? Anything to adjust, remove, or add?"
+
+### 3. Discuss and Refine
+Work through the content together:
+- Validate what's accurate
+- Remove what's wrong, outdated, or hallucinated
+- Add what's missing through brief discussion
+- **Course correct** based on knowledge from subsequent project work
+- Refine wording and structure
+
+This is a **human-level conversation**, not form-filling. The user brings context from across the project that may not be in the reference material - decisions from other topics, implications from later work, or knowledge that can't all fit in context.
+
+### 4. Log When Approved
+Only when the user approves ("yes, log it", "that's good", etc.) do you write it to the specification - **verbatim** as presented and approved.
+
+### 5. Repeat
+Move to the next topic.
+
+## Context Resurfacing
+
+When you discover information that affects **already-logged topics**, resurface them. Even mid-discussion - interrupt, flag what you found, and discuss whether it changes anything.
+
+If it does: summarize what's changing in the chat, then re-present the full updated topic. The summary is for discussion only - the specification just gets the clean replacement. Standard workflow applies: user approves before you update.
+
+This is encouraged. Better to resurface and confirm "already covered" than let something slip past.
+
+## The Specification Document
+
+Create `docs/workflow/specification/{topic}.md`
+
+This is a single file per topic. Structure is **flexible** - organize around phases and subject matter, not rigid sections. This is a working document.
+
+Suggested skeleton:
+
+```markdown
+# Specification: [Topic Name]
+
+**Status**: Building specification
+**Last Updated**: [timestamp]
+
+---
+
+## Specification
+
+[Validated content accumulates here, organized by topic/phase]
+
+---
+
+## Working Notes
+
+[Optional - capture in-progress discussion if needed]
+```
+
+## Critical Rules
+
+**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.
+
+**Commit frequently**: Commit at natural breaks and before any context refresh. Context refresh = lost work.
+
+**Trust nothing without validation**: Synthesize and present, but never assume source material is correct.
+
+## After Context Refresh
+
+Read the specification. It contains validated, approved content. Trust it - you built it together with the user.
+
+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.
+
+The same workflow applies: present the dependencies section for approval, then log verbatim when approved.
+
+### 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)
+
+### Categorization
+
+**Required**: Cannot proceed without this. Core functionality depends on it.
+
+**Partial Requirement**: Only specific elements are needed, not the full system. Note the minimum scope.
+
+### Format
+
+## Dependencies
+
+Systems referenced in this specification that need to exist before implementation:
+
+### Required
+
+| Dependency | Why Needed | Blocking Elements |
+|------------|------------|-------------------|
+| **[System Name]** | [Brief explanation of why] | [What parts of this spec are blocked] |
+
+### Partial Requirement
+
+| Dependency | Why Needed | Minimum Scope |
+|------------|------------|---------------|
+| **[System Name]** | [Brief explanation] | [What subset is actually needed] |
+
+### Notes
+
+- [Any clarifications about what can be built independently]
+- [Workarounds or alternatives 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.
+
+## Transitioning to Formal Planning
+
+Specification is complete when:
+- All topics/phases have validated content
+- User confirms the specification is complete
+- No blocking gaps remain
+
+Then proceed to formal planning with the **technical-planning** skill.