@leeovery/claude-technical-workflows 2.1.18 → 2.1.20

package/skills/technical-review/SKILL.md

@@ -6,17 +6,7 @@ user-invocable: false
 
 # Technical Review
 
-Act as a **senior software architect** with deep experience in code review. You haven't seen this code before. Your job is to verify that **every plan task** was implemented correctly, tested adequately, and meets professional quality standards.
-
-This is **product review**, **feature review**, **test review**, AND **code review**. Not just "does the code work?" but "was every task done correctly, tested properly, and built to professional standards?"
-
-## Review Artifacts
-
-This skill reviews against available artifacts. Required:
-- **Plan** (the tasks and acceptance criteria)
-
-Optional but helpful:
-- **Specification** (context for design decisions)
+Act as a **senior software architect** with deep experience in code review. You haven't seen this code before. Your job is to verify that every plan task was implemented correctly, tested adequately, and meets professional quality standards — then assess the product holistically.
 
 ## Purpose in the Workflow
 
@@ -24,13 +14,13 @@ This skill can be used:
 - **Sequentially**: After implementation of a planned feature
 - **Standalone** (Contract entry): To review any implementation against a plan
 
-Either way: Verify every plan task was implemented, tested adequately, and meets quality standards.
+Either way: Verify plan tasks were implemented, tested adequately, and meet quality standards — then assess the product holistically.
 
 ### What This Skill Needs
 
-- **Plan content** (required) - Tasks and acceptance criteria to verify against
+- **Review scope** (required) - single, multi, or all
+- **Plan content** (required) - Tasks and acceptance criteria to verify against (one or more plans)
 - **Specification content** (optional) - Context for design decisions
-- **Implementation scope** (optional) - What code/files to review. Will identify from git if not specified.
 
 **Before proceeding**, verify the required input is available. If anything is missing, **STOP** — do not proceed until resolved.
 
@@ -57,83 +47,91 @@ Do not guess at progress or continue from memory. The files on disk and git hist
 
 ---
 
-## Review Approach
+## Hard Rules
+
+1. **Review ALL tasks** — Don't sample; verify every planned task
+2. **Don't fix code** — Identify problems, don't solve them
+3. **Don't re-implement** — You're reviewing, not building
+4. **Be specific** — "Test doesn't cover X" not "tests need work"
+5. **Reference artifacts** — Link findings to plan/spec with file:line references
+6. **Balanced test review** — Flag both under-testing AND over-testing
+7. **Fresh perspective** — You haven't seen this code before; question everything
+
+## Output Formatting
+
+When announcing a new step, output `── ── ── ── ──` on its own line before the step heading.
+
+---
+
+## Step 1: Read Plan(s) and Specification(s)
 
-Start from the **plan** - it contains the granular tasks and acceptance criteria.
+Read all plan(s) provided for the selected scope.
 
-Use the **specification** for context if available. If no specification exists, the plan is the source of truth for design decisions.
+For each plan:
+1. Read the plan — understand phases, tasks, and acceptance criteria
+2. Read the linked specification if available — load design context
+3. Extract all tasks across all phases
 
-Verify **all** tasks, not a sample.
+If no specification exists, the plan is the sole source of truth for design decisions.
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Project Skills Discovery
+
+#### If `.claude/skills/` does not exist or is empty
 
 ```
-Plan (tasks + acceptance criteria)
-    ↓
-    For EACH task:
-        → Load Spec Context (deeper understanding)
-        → Verify Implementation (code exists, correct)
-        → Verify Tests (adequate, not over/under tested)
-        → Check Code Quality (readable, conventions)
+No project skills found. Proceeding without project-specific conventions.
 ```
 
-**Use parallel `review-task-verifier` subagents** to verify ALL plan tasks simultaneously. Each verifier checks one task for implementation, tests, and quality. This enables comprehensive review without sequential bottlenecks.
+→ Proceed to **Step 3**.
 
-## What You Verify (Per Task)
+#### If project skills exist
 
-### Implementation
+Scan `.claude/skills/` for project-specific skill directories. Note which are relevant to the review (framework guidelines, code style, architecture patterns).
 
-- Is the task implemented?
-- Does it match the acceptance criteria?
-- Does it align with spec context?
-- Any drift from what was planned?
+→ Proceed to **Step 3**.
 
-### Tests
+---
 
-Evaluate test coverage critically - both directions:
+## Step 3: QA Verification
 
-- **Not under-tested**: Does a test exist? Does it verify acceptance criteria? Are edge cases covered?
-- **Not over-tested**: Are tests focused and necessary? No redundant or bloated checks?
-- Would the test fail if the feature broke?
+Load **[invoke-task-verifiers.md](references/invoke-task-verifiers.md)** and follow its instructions as written.
 
-### Code Quality
+**STOP.** Do not proceed until ALL task verifiers have returned and findings are aggregated.
 
-Review as a senior architect would:
+→ Proceed to **Step 4**.
 
-**Project conventions** (check `.claude/skills/` for project-specific guidance):
-- Framework and architecture guidelines
-- Code style and patterns specific to the project
+---
 
-**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
-- **Performance**: No obvious inefficiencies
+## Step 4: Product Assessment
 
-## Review Process
+Load **[invoke-product-assessor.md](references/invoke-product-assessor.md)** and follow its instructions as written.
 
-1. **Read the plan** - Understand all phases, tasks, and acceptance criteria
-2. **Read the specification** - Load context for the feature being reviewed
-3. **Extract all tasks** - List every task from every phase
-4. **Spawn review-task-verifiers in parallel** - One subagent per task, all running simultaneously
-5. **Aggregate findings** - Collect reports from all review-task-verifiers
-6. **Check project skills** - Framework/language conventions
-7. **Produce review** - Structured feedback covering all tasks
+**STOP.** Do not proceed until the product assessor has returned.
 
-See **[review-checklist.md](references/review-checklist.md)** for detailed checklist.
+→ Proceed to **Step 5**.
 
-## Hard Rules
+---
+
+## Step 5: Produce Review
 
-1. **Review ALL tasks** - Don't sample; verify every planned task
-2. **Don't fix code** - Identify problems, don't solve them
-3. **Don't re-implement** - You're reviewing, not building
-4. **Be specific** - "Test doesn't cover X" not "tests need work"
-5. **Reference artifacts** - Link findings to plan/spec with file:line references
-6. **Balanced test review** - Flag both under-testing AND over-testing
-7. **Fresh perspective** - You haven't seen this code before; question everything
+Aggregate findings from both stages into a review document using the **[template.md](references/template.md)**.
 
-## What Happens After Review
+Write the review to `docs/workflow/review/{topic}.md` (single) or `docs/workflow/review/{scope-description}.md` (multi/all).
+
+**QA Verdict** (from Step 3):
+- **Approve** — All acceptance criteria met, no blocking issues
+- **Request Changes** — Missing requirements, broken functionality, inadequate tests
+- **Comments Only** — Minor suggestions, non-blocking observations
+
+**Product Assessment** (from Step 4) — always advisory, presented alongside the verdict.
+
+Commit: `review({topic}): complete review`
+
+Present the review to the user.
 
 Your review feedback can be:
 - Addressed by implementation (same or new session)
@@ -142,7 +140,11 @@ Your review feedback can be:
 
 You produce feedback. User decides what to do with it.
 
+---
+
 ## References
 
-- **[template.md](references/template.md)** - Review output structure and verdict guidelines
-- **[review-checklist.md](references/review-checklist.md)** - Detailed review checklist
+- **[invoke-task-verifiers.md](references/invoke-task-verifiers.md)** — How to dispatch QA verifier agents
+- **[invoke-product-assessor.md](references/invoke-product-assessor.md)** — How to dispatch the product assessor agent
+- **[template.md](references/template.md)** — Review output structure and verdict guidelines
+- **[review-checklist.md](references/review-checklist.md)** — Per-task verification criteria (read by agents), plan completion checks, writing feedback guidance

package/skills/technical-review/references/invoke-product-assessor.md

@@ -0,0 +1,57 @@
+# Invoke Product Assessor
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+This step dispatches a single `review-product-assessor` agent to evaluate the implementation holistically as a product. This is not task-by-task — the assessor evaluates robustness, gaps, and product readiness.
+
+---
+
+## Identify Scope
+
+Determine the review scope indicator to pass to the assessor:
+
+- **single-plan** — one plan selected
+- **multi-plan** — multiple plans selected
+- **full-product** — all implemented plans
+
+Build the full list of implementation files across all plans in scope (same git history approach as QA verification).
+
+---
+
+## Dispatch Assessor
+
+Dispatch **one agent** via the Task tool.
+
+- **Agent path**: `../../../agents/review-product-assessor.md`
+
+The assessor receives:
+
+1. **Implementation files** — all files in scope (the full list, not summarized)
+2. **Specification path(s)** — from each plan's frontmatter
+3. **Plan path(s)** — all plans in scope
+4. **Project skill paths** — from Step 2 discovery
+5. **Review scope** — one of: `single-plan`, `multi-plan`, `full-product`
+
+---
+
+## Wait for Completion
+
+**STOP.** Do not proceed until the assessor has returned.
+
+The assessor writes its findings to `docs/workflow/review/{topic-or-scope}/product-assessment.md` and returns a brief status. If the agent fails (error, timeout), record the failure and continue to the review production step with QA findings only.
+
+---
+
+## Expected Result
+
+The assessor returns:
+
+```
+STATUS: findings | clean
+FINDINGS_COUNT: {N}
+SUMMARY: {1 sentence}
+```
+
+The full findings are in the output file. Read `docs/workflow/review/{topic-or-scope}/product-assessment.md` to incorporate into the review document.

package/skills/technical-review/references/invoke-task-verifiers.md

@@ -0,0 +1,104 @@
+# Invoke Task Verifiers
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+This step dispatches `review-task-verifier` agents in parallel to verify ALL tasks across the selected plan(s). Each verifier independently checks one task for implementation, tests, and code quality.
+
+---
+
+## Identify Scope
+
+Build the list of implementation files using git history. For each plan in scope:
+
+```bash
+git log --oneline --name-only --pretty=format: --grep="impl({topic}):" | sort -u | grep -v '^$'
+```
+
+This captures all files touched by implementation commits for the topic.
+
+---
+
+## Extract All Tasks
+
+From each plan in scope, list every task across all phases:
+- Note each task's description
+- Note each task's acceptance criteria
+- Note expected micro acceptance (test name)
+
+---
+
+## Dispatch Verifiers
+
+Dispatch **one verifier per task, all in parallel** via the Task tool.
+
+- **Agent path**: `../../../agents/review-task-verifier.md`
+
+Each verifier receives:
+
+1. **Plan task** — the specific task with acceptance criteria
+2. **Specification path** — from the plan's frontmatter (if available)
+3. **Plan path** — the full plan for phase context
+4. **Project skill paths** — from Step 2 discovery
+5. **Review checklist path** — `skills/technical-review/references/review-checklist.md`
+
+---
+
+## Wait for Completion
+
+**STOP.** Do not proceed until all verifiers have returned.
+
+Each verifier returns a structured finding. If any verifier fails (error, timeout), record the failure and continue — aggregate what's available.
+
+---
+
+## Expected Result
+
+Each verifier returns:
+
+```
+TASK: [Task name/description]
+
+ACCEPTANCE CRITERIA: [List from plan]
+
+STATUS: Complete | Incomplete | Issues Found
+
+SPEC CONTEXT: [Brief summary of relevant spec context]
+
+IMPLEMENTATION:
+- Status: [Implemented/Missing/Partial/Drifted]
+- Location: [file:line references]
+- Notes: [Any concerns]
+
+TESTS:
+- Status: [Adequate/Under-tested/Over-tested/Missing]
+- Coverage: [What is/isn't tested]
+- Notes: [Specific issues]
+
+CODE QUALITY:
+- Project conventions: [Followed/Violations/N/A]
+- SOLID principles: [Good/Concerns]
+- Complexity: [Low/Acceptable/High]
+- Modern idioms: [Yes/Opportunities]
+- Readability: [Good/Concerns]
+- Issues: [Specific problems if any]
+
+BLOCKING ISSUES:
+- [List any issues that must be fixed]
+
+NON-BLOCKING NOTES:
+- [Suggestions for improvement]
+```
+
+---
+
+## Aggregate Findings
+
+Once all verifiers have returned, synthesize their reports:
+
+- Collect all tasks with `STATUS: Incomplete` or `STATUS: Issues Found` as blocking issues
+- Collect all test issues (under/over-tested)
+- Collect all code quality concerns
+- Include specific file:line references
+- Check overall plan completion (see [review-checklist.md](review-checklist.md) — Plan Completion Check)

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

@@ -4,61 +4,7 @@
 
 ---
 
-## Before Starting
-
-1. Read plan (from the location provided)
-   - If not found at expected path, ask user where the plan is
-2. Read specification if available and linked in plan
-   - Not required, but helpful for context if it exists
-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 `review-task-verifier` subagents **in parallel** for ALL tasks:
-
-```
-Task 1 ──▶ [review-task-verifier] ──▶ Findings
-Task 2 ──▶ [review-task-verifier] ──▶ Findings
-Task 3 ──▶ [review-task-verifier] ──▶ Findings  (all running in parallel)
-Task 4 ──▶ [review-task-verifier] ──▶ Findings
-  ...
-Task N ──▶ [review-task-verifier] ──▶ Findings
-```
-
-**How to invoke each review-task-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 review-task-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 review-task-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
+## Per-Task Verification Criteria
 
 For each task, the review-task-verifier checks:
 

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

@@ -7,34 +7,55 @@
 ## Template
 
 ```markdown
-# Implementation Review: {Topic}
+# Implementation Review: {Topic / Product}
 
-**Verdict**: Approve | Request Changes | Comments Only
+**Scope**: Single Plan ({plan}) | Multi-Plan ({plans}) | Full Product
+**QA Verdict**: Approve | Request Changes | Comments Only
 
 ## Summary
 [One paragraph overall assessment]
 
-## Specification Compliance
+## QA Verification
+
+### Specification Compliance
 [Implementation aligns with specification / Note any deviations]
 
-## Plan Completion
-- [ ] Phase 1 acceptance criteria met
-- [ ] Phase 2 acceptance criteria met
+### Plan Completion
+- [ ] Phase N acceptance criteria met
 - [ ] All tasks completed
 - [ ] No scope creep
 
-## Code Quality
+### Code Quality
 [Issues or "No issues found"]
 
-## Test Quality
+### Test Quality
 [Issues or "Tests adequately verify requirements"]
 
-## Required Changes (if any)
+### Required Changes (if any)
 1. [Specific actionable change]
-2. [Specific actionable change]
 
-## Recommendations (optional)
-[Non-blocking suggestions]
+## Product Assessment
+
+### Robustness
+[Where would this break under real-world usage?]
+
+### Gaps
+[What's obviously missing now the product exists?]
+
+### Cross-Plan Consistency (multi/all only)
+[Are patterns consistent across features?]
+
+### Integration Seams (multi/all only)
+[Do independently-built features connect cleanly?]
+
+### Strengthening Opportunities
+[Priority improvements for production readiness]
+
+### What's Next
+[What does this enable? What should be built next?]
+
+## Recommendations
+[Combined non-blocking suggestions]
 ```
 
 ## Verdict Guidelines
@@ -44,3 +65,4 @@
 **Request Changes**: Missing requirements, deviations from decisions, broken functionality, inadequate tests
 
 **Comments Only**: Minor suggestions, style preferences, non-blocking observations
+