@leeovery/claude-technical-workflows 2.1.38 → 2.1.39

package/skills/technical-specification/references/review-tracking-format.md

@@ -0,0 +1,66 @@
+# Review Tracking Format
+
+*Reference for **[spec-review](spec-review.md)***
+
+---
+
+Review tracking files capture analysis findings so work persists across context refresh.
+
+## Location
+
+Store tracking files in the specification topic directory (`docs/workflow/specification/{topic}/`), cycle-numbered:
+- `review-input-tracking-c{N}.md` — Phase 1 findings for cycle N
+- `review-gap-analysis-tracking-c{N}.md` — Phase 2 findings for cycle N
+
+Tracking files are **never deleted**. After all findings are processed, mark `status: complete`. Previous cycles' files persist as analysis history.
+
+## Format
+
+```markdown
+---
+status: in-progress | complete
+created: YYYY-MM-DD
+cycle: {N}
+phase: Input Review | Gap Analysis
+topic: [Topic Name]
+---
+
+# Review Tracking: [Topic Name] - [Phase]
+
+## Findings
+
+### 1. [Brief Title]
+
+**Source**: [Where this came from — file/section reference, or "Specification analysis" for Gap Analysis]
+**Category**: Enhancement to existing topic | New topic | Gap/Ambiguity
+**Affects**: [Which section(s) of the specification]
+
+**Details**:
+[Explanation of what was found and why it matters]
+
+**Proposed Addition**:
+[What you would add to the specification — leave blank until discussed]
+
+**Resolution**: Pending | Approved | Adjusted | Skipped
+**Notes**: [Any discussion notes or adjustments made]
+
+---
+
+### 2. [Next Finding]
+...
+```
+
+## Workflow with Tracking Files
+
+1. Complete your analysis and create the tracking file with all findings
+2. Commit the tracking file — ensures it survives context refresh
+3. Present the summary to the user (from the tracking file)
+4. Work through items one at a time:
+   - Present the item
+   - Discuss and refine
+   - Get approval
+   - Log to specification
+   - Update the tracking file: mark resolution, add notes
+5. After all items resolved, mark tracking file `status: complete`
+
+**Why tracking files**: If context refreshes mid-review, you can read the tracking file and continue where you left off. The tracking file shows which items are resolved and which remain. This is especially important when reviews surface 10-20 items that need individual discussion.

package/skills/technical-specification/references/spec-completion.md

@@ -0,0 +1,114 @@
+# Specification Completion
+
+*Reference for **[technical-specification](../SKILL.md)***
+
+---
+
+## Step 1: Determine Specification Type
+
+Before asking for sign-off, assess whether this is a **feature** or **cross-cutting** specification. See **[specification-format.md](specification-format.md)** for type definitions.
+
+**Feature specification** — Something to build:
+- Has concrete deliverables (code, APIs, UI)
+- Can be planned with phases, tasks, acceptance criteria
+- Results in a standalone implementation
+
+**Cross-cutting specification** — Patterns/policies that inform other work:
+- Defines "how to do things" rather than "what to build"
+- Will be referenced by multiple feature specifications
+- Implementation happens within features that apply these patterns
+
+Present your assessment to the user:
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+This specification appears to be a **[feature/cross-cutting]** specification.
+
+[Brief rationale — e.g., "It defines a caching strategy that will inform how multiple features handle data retrieval, rather than being a standalone piece of functionality to build."]
+
+- **Feature specs** proceed to planning and implementation
+- **Cross-cutting specs** are referenced by feature plans but don't have their own implementation plan
+
+Does this assessment seem correct?
+```
+
+**STOP.** Wait for user confirmation before proceeding.
+
+---
+
+## Step 2: Verify Tracking Files Complete
+
+Before proceeding to sign-off, confirm that all review tracking files across all cycles have `status: complete`:
+
+- `review-input-tracking-c{N}.md` — should be marked complete after each Phase 1
+- `review-gap-analysis-tracking-c{N}.md` — should be marked complete after each Phase 2
+
+If any tracking file still shows `status: in-progress`, mark it complete now.
+
+> **CHECKPOINT**: Do not proceed to sign-off if any tracking files still show `status: in-progress`. They indicate incomplete review work.
+
+---
+
+## Step 3: Sign-Off
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`y`/`yes`** — Conclude specification and mark as concluded
+- **Comment** — Add context before concluding
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If comment
+
+Discuss the user's context, apply any changes, then re-present the sign-off prompt above.
+
+#### If yes
+
+→ Proceed to **Step 4**.
+
+---
+
+## Step 4: Update Frontmatter and Conclude
+
+Update the specification frontmatter:
+
+```yaml
+---
+topic: {topic-name}
+status: concluded
+type: feature  # or cross-cutting, as confirmed
+date: YYYY-MM-DD  # Use today's actual date
+review_cycle: {N}
+finding_gate_mode: gated
+---
+```
+
+Specification is complete when:
+- All topics have validated content
+- All sources are marked as `incorporated`
+- At least one review cycle completed with no findings, OR user explicitly chose to proceed past the re-loop prompt
+- All review tracking files marked `status: complete`
+- Type has been determined and confirmed
+- User confirms the specification is complete
+- No blocking gaps remain
+
+Commit: `spec({topic}): conclude specification`
+
+---
+
+## Step 5: Handle Source Specifications
+
+If any of your sources were **existing specifications** (as opposed to discussions, research, or other reference material), these have now been consolidated into the new specification.
+
+1. Mark each source specification as superseded by updating its frontmatter:
+   ```yaml
+   status: superseded
+   superseded_by: {new-specification-name}
+   ```
+2. Inform the user which files were updated
+3. Commit: `spec({topic}): mark source specifications as superseded`

package/skills/technical-specification/references/spec-construction.md

@@ -0,0 +1,109 @@
+# Spec Construction
+
+*Reference for **[technical-specification](../SKILL.md)***
+
+---
+
+Follow stages A through F sequentially for each topic in the specification. Each topic completes a full cycle before the next begins.
+
+```
+A. Exhaustive extraction from sources
+B. Synthesize and present for approval
+C. Discuss and refine (if needed)
+D. Approval gate
+E. Log and commit
+F. Topic complete → loop back to A or exit
+```
+
+---
+
+## A. Exhaustive Extraction
+
+Load **[exhaustive-extraction.md](exhaustive-extraction.md)** and follow its instructions for the current topic.
+
+When working with multiple sources, search each one — information about a single topic may be scattered across documents.
+
+### Context Resurfacing
+
+When extraction reveals information that affects **already-logged topics**, resurface them immediately. 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.**
+
+> **CHECKPOINT**: Even when resurfacing content, you MUST NOT update the specification until the user explicitly approves the change. Present the updated version, wait for approval, then update.
+
+Better to resurface and confirm "already covered" than let something slip past.
+
+---
+
+## B. Synthesize and Present
+
+Present your understanding to the user **in the format it would appear in the specification**:
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+Here's what I understand about [topic] based on the reference material. This is exactly what I'll write into the specification:
+
+[content as rendered markdown]
+```
+
+Then, **separately from the content above** (clear visual break):
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+**To proceed:**
+- **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim** (exactly as shown, no modifications).
+- **Or tell me what to change.**
+· · · · · · · · · · · ·
+```
+
+Content and choices must be visually distinct (not run together).
+
+> **CHECKPOINT**: After presenting, you MUST STOP and wait for the user's response. Do NOT proceed to logging. Do NOT present the next topic. WAIT.
+
+---
+
+## C. 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.
+
+---
+
+## D. Approval Gate
+
+**DO NOT PROCEED TO LOGGING WITHOUT EXPLICIT USER APPROVAL.**
+
+If you are uncertain whether the user approved, **ASK**: "Ready to log it, or do you want to change something?"
+
+> **CHECKPOINT**: If you are about to write to the specification and the user's last message was not explicit approval, **STOP**. Present the choices again.
+
+---
+
+## E. Log and Commit
+
+1. Write to the specification — **verbatim** as presented and approved. No silent modifications.
+2. After completing exhaustive extraction from a source (all relevant content presented and logged), update that source's status to `incorporated` in the specification frontmatter. See **[specification-format.md](specification-format.md)** for source status details.
+3. Commit at natural breaks — after significant exchanges, after each major topic, and before any context refresh.
+
+---
+
+## F. Topic Complete
+
+This is the end of this iteration.
+
+#### If additional topics remain
+
+→ Proceed to **A. Exhaustive Extraction** and follow the instructions as written.
+
+#### If all topics are covered
+
+→ Return to **[technical-specification SKILL.md](../SKILL.md)** for **Step 5**.

package/skills/technical-specification/references/spec-review.md

@@ -0,0 +1,154 @@
+# Specification Review
+
+*Reference for **[technical-specification](../SKILL.md)***
+
+---
+
+Two-phase review of the specification. Phase 1 (Input Review) compares against source material. Phase 2 (Gap Analysis) reviews the specification as a standalone document.
+
+**Why this matters**: The specification is the golden document. Plans are built from it, and those plans inform implementation. If a detail isn't in the specification, it won't make it to the plan, and therefore won't be built. Worse, the implementation agent may hallucinate to fill gaps, potentially getting it wrong. The goal is a specification robust enough that an agent or human could pick it up, create plans, break it into tasks, and write the code.
+
+Load **[review-tracking-format.md](review-tracking-format.md)** — internalize the tracking file format for both phases.
+
+---
+
+## A. Cycle Management
+
+Check the `review_cycle` field in the specification frontmatter.
+
+#### If `review_cycle` is 0 or not set
+
+Set `review_cycle: 1` in the specification frontmatter.
+
+#### If `review_cycle` is already set
+
+Increment `review_cycle` by 1.
+
+Record the current cycle number — used for tracking file naming (`c{N}`).
+
+Commit the updated frontmatter.
+
+→ If `review_cycle <= 3`, proceed to **B. Phase 1 — Input Review**.
+
+#### If `review_cycle > 3`
+
+**Do NOT skip review autonomously.** This gate is an escape hatch for the user — not a signal to stop. The expected default is to continue running review until no issues are found. Present the choice and let the user decide.
+
+> *Output the next fenced block as a code block:*
+
+```
+Review cycle {N}
+
+Review has run {N-1} times so far. You can continue (recommended if issues
+were still found last cycle) or skip to completion.
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`p`/`proceed`** — Continue review *(default)*
+- **`s`/`skip`** — Skip review, proceed to completion
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user choice. You MUST NOT choose on the user's behalf.
+
+#### If `proceed`
+
+→ Continue to **B. Phase 1 — Input Review**.
+
+#### If `skip`
+
+→ Jump to **E. Completion**.
+
+---
+
+## B. Phase 1 — Input Review
+
+1. Load **[review-input.md](review-input.md)** and follow its instructions (analysis + tracking file creation).
+2. Load **[process-review-findings.md](process-review-findings.md)** and follow its instructions to process findings with the user.
+
+→ Proceed to **C. Phase 2 — Gap Analysis**.
+
+---
+
+## C. Phase 2 — Gap Analysis
+
+1. Load **[review-gap-analysis.md](review-gap-analysis.md)** and follow its instructions (analysis + tracking file creation).
+2. Load **[process-review-findings.md](process-review-findings.md)** and follow its instructions to process findings with the user.
+
+→ Proceed to **D. Re-Loop Prompt**.
+
+---
+
+## D. Re-Loop Prompt
+
+#### If no findings were surfaced in either phase of this cycle
+
+→ Skip the re-loop prompt and proceed directly to **E. Completion** (nothing to re-analyse).
+
+#### If findings were surfaced
+
+Check `finding_gate_mode` and `review_cycle` in the specification frontmatter.
+
+#### If `finding_gate_mode: auto` and `review_cycle < 5`
+
+> *Output the next fenced block as a code block:*
+
+```
+Review cycle {N} complete — findings applied. Running follow-up cycle.
+```
+
+→ Return to **A. Cycle Management**.
+
+#### If `finding_gate_mode: auto` and `review_cycle >= 5`
+
+> *Output the next fenced block as a code block:*
+
+```
+Review cycle {N}
+
+Auto-review has not converged after 5 cycles — escalating for human review.
+```
+
+→ Present the gated re-loop prompt below.
+
+#### If `finding_gate_mode: gated`
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`r`/`reanalyse`** — Run another review cycle (Phase 1 + Phase 2)
+- **`p`/`proceed`** — Proceed to completion
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If reanalyse
+
+→ Return to **A. Cycle Management** to begin a fresh cycle.
+
+#### If proceed
+
+→ Continue to **E. Completion**.
+
+---
+
+## E. Completion
+
+1. **Verify tracking files are marked complete** — All input review and gap analysis tracking files across all cycles must have `status: complete`.
+
+> **CHECKPOINT**: Do not confirm completion if any tracking files still show `status: in-progress`. They indicate incomplete review work.
+
+2. **Commit** all review tracking files: `spec({topic}): complete specification review (cycle {N})`
+
+> *Output the next fenced block as a code block:*
+
+```
+Specification review complete — {N} cycle(s), all tracking files finalised.
+```
+
+→ Return to **[technical-specification SKILL.md](../SKILL.md)** for **Step 7**.

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

@@ -0,0 +1,166 @@
+# Specification Format
+
+*Reference for **[technical-specification](../SKILL.md)***
+
+---
+
+This file defines the canonical structure for specification files (`docs/workflow/specification/{topic}/specification.md`).
+
+The specification is a single file per topic. Structure is **flexible** — organize around phases and subject matter, not rigid sections. This is a working document.
+
+> **CHECKPOINT**: You should NOT be creating or writing to this file unless you have explicit user approval for specific content. If you're about to create this file with content you haven't presented and had approved, **STOP**. That violates the workflow.
+
+---
+
+## Frontmatter
+
+```yaml
+---
+topic: {topic-name}
+status: in-progress
+type: feature
+date: YYYY-MM-DD
+review_cycle: 0
+finding_gate_mode: gated
+sources:
+  - name: {source-name}
+    status: pending
+---
+```
+
+| Field | Set when |
+|-------|----------|
+| `topic` | Spec creation (Step 2) — kebab-case identifier matching the directory name |
+| `status` | Spec creation → `in-progress`; conclusion → `concluded` |
+| `type` | Spec creation → `feature` (default); completion → `feature` or `cross-cutting` |
+| `date` | Spec creation — today's date; update on each commit |
+| `review_cycle` | Starts at 0; incremented each review cycle. Missing field treated as 0. |
+| `finding_gate_mode` | Spec creation → `gated`; user opts in → `auto` |
+| `sources` | Spec creation — all sources as `pending`; updated as extraction completes |
+
+---
+
+## Body
+
+```markdown
+# Specification: [Topic Name]
+
+## Specification
+
+[Validated content accumulates here, organized by topic/phase]
+
+---
+
+## Working Notes
+
+[Optional - capture in-progress discussion if needed]
+```
+
+---
+
+## Sources and Incorporation Status
+
+**All specifications must track their sources**, even when built from a single source. This enables proper tracking when additional material is later added.
+
+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 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
+
+The `type` field distinguishes between specifications that result in standalone implementation work versus those that inform how other work is done.
+
+### Feature Specifications (`type: feature`)
+
+Feature specifications describe something to **build** — a concrete piece of functionality with its own implementation plan.
+
+**Examples:**
+- User authentication system
+- Order processing pipeline
+- Notification service
+- Dashboard analytics
+
+**Characteristics:**
+- Results in a dedicated implementation plan
+- Has concrete deliverables (code, APIs, UI)
+- Can be planned with phases, tasks, and acceptance criteria
+- Progress is measurable ("the feature is done")
+
+**This is the default type.** If not specified, assume `feature`.
+
+### Cross-Cutting Specifications (`type: cross-cutting`)
+
+Cross-cutting specifications describe **patterns, policies, or architectural decisions** that inform how features are built. They don't result in standalone implementation — instead, they're referenced by feature specifications and plans.
+
+**Examples:**
+- Caching strategy
+- Rate limiting policy
+- Error handling conventions
+- Logging and observability standards
+- API versioning approach
+- Security patterns
+
+**Characteristics:**
+- Does NOT result in a dedicated implementation plan
+- Defines "how to do things" rather than "what to build"
+- Referenced by multiple feature specifications
+- Implementation happens within features that apply these patterns
+- No standalone "done" state — the patterns are applied across features
+
+### Why This Matters
+
+Cross-cutting specifications go through the same validation phases. The decisions are just as important to validate and document. The difference is what happens after:
+
+- **Feature specs** → Planning → Implementation → Review
+- **Cross-cutting specs** → Referenced by feature plans → Applied during feature implementation
+
+When planning a feature, the planning process surfaces relevant cross-cutting specifications as context. This ensures that a "user authentication" plan incorporates the validated caching strategy and error handling conventions.
+
+### Determining the Type
+
+Ask: **"Is there a standalone thing to build, or does this inform how we build other things?"**
+
+| Question | Feature | Cross-Cutting |
+|----------|---------|---------------|
+| Can you demo it when done? | Yes — "here's the login page" | No — it's invisible infrastructure |
+| Does it have its own UI/API/data? | Yes | No — lives within other features |
+| Can you plan phases and tasks for it? | Yes | Tasks would be "apply X to feature Y" |
+| Is it used by one feature or many? | Usually one | By definition, multiple |
+
+**Edge cases:**
+- A "caching service" that provides shared caching infrastructure → **Feature** (you're building something)
+- "How we use caching across the app" → **Cross-cutting** (policy/pattern)
+- Authentication system → **Feature**
+- Authentication patterns and security requirements → **Cross-cutting**