@leeovery/claude-technical-workflows 2.0.18 → 2.0.20

package/README.md

@@ -16,27 +16,23 @@
 
 ## What is this?
 
-A six-phase workflow for Claude Code that captures context, decisions, and rationale before any code is written, then implements and validates the work against those artifacts.
+A complete development workflow for Claude Code: explore ideas, capture decisions, build actionable plans, implement via strict TDD, and validate the result.
+
+Use it as a **six-phase workflow** or pick individual capabilities as needed:
 
 ```
-Research       → Explore ideas
-     ↓
-Discussion     → Debate and decide
-     ↓
-Specification  → Validate and refine
-     ↓
-Planning       → Structure the work
-     ↓
-Implementation → Build via TDD
-     ↓
-Review         → Validate against spec
+Research → Discussion → Specification → Planning → Implementation → Review
 ```
 
-**Why this matters:** Complex features benefit from thorough discussion before implementation. These skills help you document the *what* and *why* before diving into the *how*, preserving architectural decisions, edge cases, and the reasoning behind choices that would otherwise be lost.
+**Why this matters:** Complex features benefit from thorough discussion before implementation. This toolkit documents the *what* and *why* before diving into the *how*, preserving architectural decisions, edge cases, and the reasoning behind choices that would otherwise be lost.
 
-**This is a work in progress.** The workflow is being refined through real-world usage. Expect updates as patterns evolve.
+**Flexible entry points:** Need the full workflow? Start at Research or Discussion and progress through each phase. Already know what you're building? Jump straight to Specification with `/start-feature`. Skills are input-agnostic - commands gather context and feed it to them.
 
-**Model compatibility:** These skills have been developed and refined for Claude Code running on **Opus 4.5**. Different models may exhibit different edge cases, and future model releases may require adjustments to the prompts and workflows.
+> [!NOTE]
+> **Work in progress.** The workflow is being refined through real-world usage. Expect updates as patterns evolve.
+
+> [!IMPORTANT]
+> **Model compatibility:** These skills have been developed and refined for Claude Code running on **Opus 4.5**. Different models may exhibit different edge cases, and future model releases may require adjustments to the prompts and workflows.
 
 ### Quick Install
 
@@ -55,28 +51,55 @@ See [Installation](#installation) for details and trade-offs.
 
 ## How do I use it?
 
-You have two entry points:
-
-| Start here... | When... | Command |
-|---------------|---------|---------|
-| **Research** | You have a fresh idea to explore: feasibility, market, viability, early thoughts | `/workflow:start-research` |
-| **Discussion** | You already know what you're building and need to iron out the details | `/workflow:start-discussion` |
+### Two Ways to Use the Skills
 
-**Research** is a free-for-all. Explore broadly, follow tangents, challenge assumptions. Not everything researched gets built, and that's fine. Use this for ideas that need validating before you commit.
-
-**Discussion** is where you work through the challenging parts: core architecture, edge cases, non-obvious decisions. The key value is that it captures *how* you arrived at decisions, not just the decisions themselves. When you explore four approaches and pick one, the document explains why you rejected the others. This context is invaluable later.
-
-Then follow the flow:
+**1. Full Workflow** - Sequential phases that build on each other:
 
 ```
 Research → Discussion → Specification → Planning → Implementation → Review
 ```
 
-Each phase builds on the previous. Specification validates your discussions into a standalone doc. Planning breaks that into tasks. Implementation executes via TDD. Review validates against the spec.
+Start with `/workflow:start-research` or `/workflow:start-discussion` and follow the flow. Each phase outputs files that the next phase consumes.
+
+**2. Standalone Commands** - Jump directly to a skill with flexible inputs:
+
+| Command | What it does |
+|---------|-------------|
+| `/start-feature` | Create a spec directly from inline context (skip research/discussion) |
+
+*More standalone commands coming soon.*
+
+### The Command/Skill Architecture
+
+**Skills are input-agnostic.** They don't know or care where their inputs came from: a discussion document, inline context, or external sources. They just process what they receive.
+
+**Commands are the input layer.** They gather context (from files, prompts, or inline) and pass it to skills. This separation means:
+
+- The same skill can be invoked from different entry points
+- You can create custom commands that feed skills in new ways
+- Skills remain reusable without coupling to specific workflows
 
-### Commands
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        COMMANDS                             │
+│  (gather inputs from files, prompts, inline context)        │
+├─────────────────────────────────────────────────────────────┤
+│  /workflow:start-spec     /start-feature    (your custom)   │
+│         │                       │                 │         │
+│         └───────────┬───────────┘                 │         │
+│                     ▼                             ▼         │
+├─────────────────────────────────────────────────────────────┤
+│                         SKILLS                              │
+│  (process inputs without knowing their source)              │
+├─────────────────────────────────────────────────────────────┤
+│           technical-specification skill                     │
+│           technical-planning skill                          │
+│           technical-implementation skill                    │
+│           etc.                                              │
+└─────────────────────────────────────────────────────────────┘
+```
 
-Each phase has a command designed as its entry point. Commands are prefixed with `workflow:` to indicate they're part of the sequential workflow system:
+### Workflow Commands
 
 | Phase          | Command                          |
 |----------------|----------------------------------|
@@ -87,7 +110,7 @@ Each phase has a command designed as its entry point. Commands are prefixed with
 | Implementation | `/workflow:start-implementation` |
 | Review         | `/workflow:start-review`         |
 
-Run the command directly or ask Claude to run it. Each command gathers the context it needs, asking what you're researching, discussing, or planning. Where relevant, it looks at outputs from the previous phase and offers you a choice from the list.
+Run the command directly or ask Claude to run it. Each gathers context from previous phase outputs and passes it to the skill.
 
 ## Installation
 
@@ -111,7 +134,7 @@ Skills are cached globally. They won't be available in Claude Code for Web since
 npm install -D @leeovery/claude-technical-workflows
 ```
 
-Skills are copied to `.claude/` and can be committed—giving you ownership and making them available everywhere including Claude Code for Web.
+Skills are copied to `.claude/` and can be committed, giving you ownership and making them available everywhere including Claude Code for Web.
 
 <details>
 <summary>pnpm users</summary>
@@ -137,7 +160,7 @@ npx claude-manager remove @leeovery/claude-technical-workflows && npm rm @leeove
 
 ## The Six-Phase Workflow
 
-This package enforces a deliberate progression through six distinct phases:
+When using the full workflow, it progresses through six distinct phases:
 
 ```
 ┌───────────────┐   ┌───────────────┐   ┌───────────────┐   ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
@@ -158,7 +181,7 @@ This package enforces a deliberate progression through six distinct phases:
 
 **Phase 1 - Research:** Explore ideas from their earliest seed. Investigate market fit, technical feasibility, business viability. Free-flowing exploration that may or may not lead to building something.
 
-**Phase 2 - Discussion:** Captures the back-and-forth exploration of a problem. Documents competing solutions, why certain approaches won or lost, edge cases discovered, and the journey to decisions—not just the decisions themselves.
+**Phase 2 - Discussion:** Captures the back-and-forth exploration of a problem. Documents competing solutions, why certain approaches won or lost, edge cases discovered, and the journey to decisions, not just the decisions themselves.
 
 **Phase 3 - Specification:** Transforms discussion documentation into a validated, standalone specification. Filters hallucinations and inaccuracies, enriches gaps through discussion, and builds a document that planning can execute against without referencing other sources.
 
@@ -166,23 +189,13 @@ This package enforces a deliberate progression through six distinct phases:
 
 **Phase 5 - Implementation:** Executes the plan using strict TDD. Writes tests first, implements to pass, commits frequently, and stops for user approval between phases.
 
-**Phase 6 - Review:** Validates completed work against specification requirements and plan acceptance criteria. The specification is the validated source of truth—earlier phases may contain rejected ideas that were intentionally filtered out. Provides structured feedback without fixing code directly.
-
-## How It Works
+**Phase 6 - Review:** Validates completed work against specification requirements and plan acceptance criteria. The specification is the validated source of truth; earlier phases may contain rejected ideas that were intentionally filtered out. Provides structured feedback without fixing code directly.
 
-This package depends on [`@leeovery/claude-manager`](https://github.com/leeovery/claude-manager), which:
+## Project Structure
 
-1. **Copies skills** into your project's `.claude/skills/` directory
-2. **Copies commands** into your project's `.claude/commands/` directory
-3. **Copies agents** into your project's `.claude/agents/` directory
-4. **Tracks installed plugins** via a manifest file
-5. **Handles installation/removal** automatically via npm hooks
+### Output Files
 
-You don't need to configure anything—just install and start discussing.
-
-### Output Structure
-
-Documents are stored using a **phase-first** organization:
+Documents are stored in your project using a **phase-first** organisation:
 
 ```
 docs/workflow/
@@ -202,141 +215,51 @@ Research starts with `exploration.md` and splits into topic files as themes emer
 
 ### Package Structure
 
-This package provides:
-
 ```
-skills/
-├── technical-research/        # Phase 1: Explore and validate ideas
-├── technical-discussion/      # Phase 2: Document discussions
-├── technical-specification/   # Phase 3: Build validated specifications
-├── technical-planning/        # Phase 4: Create implementation plans
-├── technical-implementation/  # Phase 5: Execute via TDD
-└── technical-review/          # Phase 6: Validate against artifacts
-
-commands/
-├── workflow:start-research.md       # Begin research exploration
-├── workflow:start-discussion.md     # Begin technical discussions
-├── workflow:start-specification.md  # Begin specification building
-├── workflow:start-planning.md       # Begin implementation planning
-├── workflow:start-implementation.md # Begin implementing a plan
-├── workflow:start-review.md         # Begin reviewing completed work
-├── link-dependencies.md             # Link dependencies across topics
-├── start-feature.md                 # Create spec directly from inline context
-└── interview.md                     # Focused questioning mode (general purpose)
+skills/                              # Input-agnostic processors
+├── technical-research/              # Explore and validate ideas
+├── technical-discussion/            # Document discussions
+├── technical-specification/         # Build validated specifications
+├── technical-planning/              # Create implementation plans
+├── technical-implementation/        # Execute via TDD
+└── technical-review/                # Validate against artefacts
+
+commands/                            # Input layer (gather context → invoke skills)
+├── workflow:start-research.md       # Sequential: begin research
+├── workflow:start-discussion.md     # Sequential: begin discussions
+├── workflow:start-specification.md  # Sequential: begin specification
+├── workflow:start-planning.md       # Sequential: begin planning
+├── workflow:start-implementation.md # Sequential: begin implementation
+├── workflow:start-review.md         # Sequential: begin review
+├── workflow:status.md               # Utility: show workflow status and next steps
+├── workflow:view-plan.md            # Utility: view plan tasks and progress
+├── start-feature.md                 # Standalone: spec from inline context
+└── link-dependencies.md             # Standalone: wire cross-topic deps
 
 agents/
-└── chain-verifier.md          # Parallel task verification for review
+└── chain-verifier.md                # Parallel task verification for review
 ```
 
 ## Skills
 
-| Skill                                                            | Phase | Description                                                                                                                                                                                                  |
-|------------------------------------------------------------------|-------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [**technical-research**](skills/technical-research/)             | 1     | Explore ideas from their earliest seed. Investigate market fit, technical feasibility, business viability. Free-flowing exploration across technical, business, and market domains.                          |
-| [**technical-discussion**](skills/technical-discussion/)         | 2     | Document technical discussions as expert architect and meeting assistant. Captures context, decisions, edge cases, competing solutions, debates, and rationale.                                              |
-| [**technical-specification**](skills/technical-specification/)   | 3     | Build validated specifications from discussion documents through collaborative refinement. Filters hallucinations, enriches gaps, produces standalone spec.                                                  |
-| [**technical-planning**](skills/technical-planning/)             | 4     | Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats.                                                                 |
-| [**technical-implementation**](skills/technical-implementation/) | 5     | Execute implementation plans using strict TDD workflow. Writes tests first, implements to pass, commits frequently, and gates phases on user approval.                                                       |
-| [**technical-review**](skills/technical-review/)                 | 6     | Review completed implementation against specification requirements and plan acceptance criteria. Uses parallel subagents for efficient chain verification. Produces structured feedback without fixing code. |
-
-### technical-research
-
-Acts as **research partner** with broad expertise spanning technical, product, business, and market domains.
-
-**Use when:**
-- Exploring a new idea from its earliest seed
-- Investigating market fit, competitors, or positioning
-- Validating technical feasibility before committing to build
-- Learning and exploration without necessarily building anything
-- Brain dumping early thoughts before formal discussion
-
-**What it does:**
-- Explores ideas freely across technical, business, and market domains
-- Prompts before documenting: "Shall I capture that?"
-- Creates research documents that may seed the discussion phase
-- Follows tangents and goes broad when useful
-
-### technical-discussion
-
-Acts as both **expert software architect** (participating in discussions) and **documentation assistant** (capturing them) simultaneously.
+Skills are **input-agnostic processors**: they receive inputs and process them without knowing where the inputs came from. This makes them reusable across different commands and workflows.
 
-**Use when:**
-- Discussing or exploring architecture and design decisions
-- Working through edge cases before specification
-- Documenting technical decisions and their rationale
-- Capturing competing solutions and why certain choices were made
-
-**What it captures:**
-- Back-and-forth debates showing how decisions were reached
-- Small details and edge cases that were discussed
-- Competing solutions and why some won over others
-- The journey—false paths, "aha" moments, course corrections
-
-### technical-specification
-
-Acts as **expert technical architect** and **specification builder**. Transforms discussion documents into validated, standalone specifications.
-
-**Use when:**
-- Ready to validate and refine discussion content
-- Need to filter potential hallucinations or inaccuracies from source material
-- Building a standalone document that planning can execute against
-- Converting discussions into verified requirements
-
-**What it produces:**
-- Validated, standalone specification document
-- Filtered content (hallucinations and inaccuracies removed)
-- Enriched content (gaps filled through discussion)
-- Clear bridge document for formal planning
-
-### technical-planning
-
-Converts specifications into structured implementation plans.
-
-**Use when:**
-- Ready to plan implementation after specification is complete
-- Need to structure how to build something with phases and concrete steps
-- Converting specification into actionable developer guidance
-
-**What it produces:**
-- Phased implementation plans with specific tasks
-- Acceptance criteria at phase and task levels
-- Multiple output formats: local markdown, Linear, Backlog.md, or Beads
-
-### technical-implementation
-
-Executes plans through strict TDD. Acts as an expert senior developer who builds quality software through disciplined test-driven development.
-
-**Use when:**
-- Implementing a plan from `docs/workflow/planning/{topic}.md`
-- Ad hoc coding that should follow TDD and quality standards
-- Bug fixes or features benefiting from structured implementation
-
-**Hard rules:**
-- No code before tests—write the failing test first
-- No test changes to pass—fix the code, not the tests
-- No scope expansion—if it's not in the plan, don't build it
-- Commit after green—every passing test is a commit point
-
-### technical-review
-
-Reviews completed work with fresh perspective. Validates implementation against prior workflow artifacts without fixing code directly.
-
-**Use when:**
-- Implementation phase is complete
-- User wants validation before merging/shipping
-- Quality gate check needed after implementation
-
-**What it checks:**
-- Were specification requirements implemented?
-- Were all plan acceptance criteria met?
-- Do tests actually verify requirements?
-- Does code follow project conventions?
+| Skill                                                            | Description                                                                                                                                                                                                  |
+|------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [**technical-research**](skills/technical-research/)             | Explore ideas from their earliest seed. Investigate market fit, technical feasibility, business viability. Free-flowing exploration across technical, business, and market domains.                          |
+| [**technical-discussion**](skills/technical-discussion/)         | Document technical discussions as expert architect and meeting assistant. Captures context, decisions, edge cases, competing solutions, debates, and rationale.                                              |
+| [**technical-specification**](skills/technical-specification/)   | Build validated specifications from source material through collaborative refinement. Filters hallucinations, enriches gaps, produces standalone spec.                                                       |
+| [**technical-planning**](skills/technical-planning/)             | Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats.                                                                 |
+| [**technical-implementation**](skills/technical-implementation/) | Execute implementation plans using strict TDD workflow. Writes tests first, implements to pass, commits frequently, and gates phases on user approval.                                                       |
+| [**technical-review**](skills/technical-review/)                 | Review completed implementation against specification requirements and plan acceptance criteria. Uses parallel subagents for efficient chain verification. Produces structured feedback without fixing code. |
 
 ## Commands
 
+Commands are the input layer: they gather context and pass it to skills. Two types:
+
 ### Workflow Commands
 
-Sequential workflow commands are prefixed with `workflow:` and expect files from previous phases.
+Sequential commands prefixed with `workflow:`. They expect files from previous phases and pass content to skills.
 
 | Command                                                                              | Description                                                                                                                                                                                                |
 |--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -347,16 +270,33 @@ Sequential workflow commands are prefixed with `workflow:` and expect files from
 | [**/workflow:start-implementation**](commands/workflow:start-implementation.md)      | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
 | [**/workflow:start-review**](commands/workflow:start-review.md)                      | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria.                                                                                                        |
 
+### Utility Commands
+
+Helpers for navigating and understanding the workflow.
+
+| Command                                                                              | Description                                                                                                                                 |
+|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| [**/workflow:status**](commands/workflow:status.md)                                  | Show workflow status - what topics exist at each phase, and suggested next steps.                                                           |
+| [**/workflow:view-plan**](commands/workflow:view-plan.md)                            | View a plan's tasks and progress, regardless of output format.                                                                              |
+
 ### Standalone Commands
 
-These commands can be used independently, without the full workflow.
+Independent commands that gather inputs flexibly (inline context, files, or prompts) and invoke skills directly. Use these when you want skill capabilities without the full workflow structure.
 
 | Command                                                 | Description                                                                                                                                 |
 |---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/start-feature**](commands/start-feature.md)         | Create a specification directly from inline context. For adding features to existing projects when you already know what you're building.  |
-| [**/interview**](commands/interview.md)                 | Shift into focused questioning mode. Probes ideas with non-obvious questions, challenges assumptions, and surfaces concerns.               |
+| [**/start-feature**](commands/start-feature.md)         | Create a specification directly from inline context. Invokes the specification skill without requiring a discussion document.              |
 | [**/link-dependencies**](commands/link-dependencies.md) | Link external dependencies across topics. Scans plans and wires up unresolved cross-topic dependencies.                                    |
 
+### Creating Custom Commands
+
+Since skills are input-agnostic, you can create your own commands that feed them in new ways. A command just needs to:
+
+1. Gather the inputs the skill expects
+2. Invoke the skill with those inputs
+
+See `/start-feature` as an example: it provides inline context to the specification skill instead of a discussion document.
+
 ## Agents
 
 Subagents that skills can spawn for parallel task execution.
@@ -383,9 +323,9 @@ Please open an issue first to discuss significant changes.
 
 ## Related Packages
 
-- [**@leeovery/claude-manager**](https://github.com/leeovery/claude-manager) — The plugin manager that powers skill installation
-- [**@leeovery/claude-laravel**](https://github.com/leeovery/claude-laravel) — Laravel development skills for Claude Code
-- [**@leeovery/claude-nuxt**](https://github.com/leeovery/claude-nuxt) — Nuxt.js development skills for Claude Code
+- [**@leeovery/claude-manager**](https://github.com/leeovery/claude-manager) - The plugin manager that powers skill installation
+- [**@leeovery/claude-laravel**](https://github.com/leeovery/claude-laravel) - Laravel development skills for Claude Code
+- [**@leeovery/claude-nuxt**](https://github.com/leeovery/claude-nuxt) - Nuxt.js development skills for Claude Code
 
 ## License
 

package/commands/workflow:status.md

@@ -0,0 +1,71 @@
+---
+description: Show workflow status - what exists, where you are, and what to do next.
+---
+
+Show the current state of the workflow for this project.
+
+## Step 1: Scan Directories
+
+Check for files in each workflow directory:
+
+```
+docs/workflow/research/
+docs/workflow/discussion/
+docs/workflow/specification/
+docs/workflow/planning/
+```
+
+## Step 2: Present Status
+
+Research is project-wide exploration. From discussion onwards, work is organised by **topic** - different topics may be at different stages.
+
+Show a summary like this:
+
+```
+## Workflow Status
+
+**Research:** 2 files (exploration.md, market-analysis.md)
+
+**Topics:**
+
+| Topic        | Discussion | Spec | Plan | Implemented |
+|--------------|------------|------|------|-------------|
+| auth-system  | ✓          | ✓    | ✓    | in progress |
+| payment-flow | ✓          | ✓    | -    | -           |
+| notifications| ✓          | -    | -    | -           |
+```
+
+Adapt based on what exists:
+- If a directory is empty or missing, show "Not started"
+- For planning, note the output format if specified in frontmatter
+- Match topics across phases by filename
+
+## Step 3: Suggest Next Steps
+
+Based on what exists, offer relevant options. Don't assume linear progression - topics may have dependencies on each other.
+
+**If nothing exists:**
+- "Start with `/workflow:start-research` to explore ideas, or `/workflow:start-discussion` if you already know what you're building."
+
+**If topics exist at various stages**, summarise options without being prescriptive:
+- Topics in discussion can move to specification
+- Topics with specs can move to planning
+- Topics with plans can move to implementation
+- Completed implementations can be reviewed
+
+Example: "auth-system has a plan ready. payment-flow needs a spec before planning. You might want to complete planning for related topics before implementing if there are dependencies."
+
+Keep suggestions brief - the user knows their project's dependencies better than we do.
+
+## Step 4: Mention Plan Viewing
+
+If planning files exist, let the user know they can view plan details:
+
+```
+To view a plan's tasks and progress, use /workflow:view-plan
+```
+
+## Notes
+
+- Keep output concise - this is a quick status check
+- Use tables for scannable information

package/commands/workflow:view-plan.md

@@ -0,0 +1,63 @@
+---
+description: View a plan's tasks and progress, regardless of output format.
+---
+
+Display a readable summary of a plan's phases, tasks, and status.
+
+## Step 1: Identify the Plan
+
+If no topic is specified, list available plans:
+
+```bash
+ls docs/workflow/planning/
+```
+
+Ask the user which plan to view.
+
+## Step 2: Read the Plan Index
+
+Read the plan file from `docs/workflow/planning/{topic}.md` and check the `format:` field in the frontmatter.
+
+## Step 3: Load Format Reference
+
+Load the corresponding output format reference:
+
+```
+skills/technical-planning/references/output-{format}.md
+```
+
+This reference contains instructions for reading plans in that format.
+
+## Step 4: Read Plan Content
+
+Follow the "Reading" or "Implementation" section in the format reference to locate and read the actual plan content.
+
+## Step 5: Present Summary
+
+Display a readable summary:
+
+```
+## Plan: {topic}
+
+**Format:** {format}
+
+### Phase 1: {phase name}
+- [ ] Task 1.1: {description}
+- [x] Task 1.2: {description}
+
+### Phase 2: {phase name}
+- [ ] Task 2.1: {description}
+...
+```
+
+Show:
+- Phase names and acceptance criteria
+- Task descriptions and status (if trackable)
+- Any blocked or dependent tasks
+
+Keep it scannable - this is for quick reference, not full detail.
+
+## Notes
+
+- Some formats (like external issue trackers) may not be fully readable without API access - note this if applicable
+- If status tracking isn't available in the format, just show the task structure

package/package.json

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

package/skills/technical-research/SKILL.md

@@ -45,7 +45,7 @@ Don't constrain yourself. Research goes wherever it needs to go.
 
 ## Questioning
 
-Use `/interview` for structured questioning. Good research questions:
+For structured questioning, use the interview reference (`references/interview.md`). Good research questions:
 
 - Reveal hidden complexity
 - Surface concerns early

package/skills/technical-research/references/interview.md

@@ -0,0 +1,35 @@
+# Interview Mode
+
+Focused questioning to probe ideas more deeply during research.
+
+## Process
+
+1. **Check existing context**: Read docs in `docs/workflow/research/` to understand what's already been explored.
+
+2. **Begin interviewing**: Use the AskUserQuestion tool to probe the idea. Focus on:
+   - Non-obvious questions (not things already answered)
+   - Assumptions and unstated constraints
+   - Tradeoffs and concerns
+   - What could go wrong
+   - The "why" behind decisions
+
+3. **Go where it leads**: Follow tangents if they reveal something valuable. This isn't a checklist - it's a conversation.
+
+4. **Document as you go**: Don't defer writing to the end. Capture insights in `docs/workflow/research/` using semantic filenames. Ask before documenting: "Shall I capture that?"
+
+5. **Commit frequently**: At natural breaks and before context refresh.
+
+6. **Exit when done**: The user decides when the interview is complete.
+
+## Question Quality
+
+Aim for questions that:
+- The user hasn't already answered
+- Reveal hidden complexity
+- Surface concerns early
+- Challenge comfortable assumptions
+
+Avoid:
+- Restating what's already documented
+- Obvious surface-level questions
+- Leading questions that assume an answer

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.

package/commands/interview.md

@@ -1,54 +0,0 @@
----
-description: Shift into focused questioning mode to probe an idea more deeply during research or discussion phases.
----
-
-Shift into focused questioning mode to probe an idea more deeply.
-
-## Setup
-
-Before beginning, ask the user:
-
-1. **What stage are you in?** Research or discussion?
-2. **What topic or idea do you want to explore?**
-
-Wait for responses before proceeding.
-
-## Process
-
-1. **Check for existing context**:
-   - Research: Look for docs in `docs/workflow/research/`
-   - Discussion: Look for the topic's file in `docs/workflow/discussion/{topic}.md`
-
-   Read what exists to understand what's already been explored.
-
-2. **Begin interviewing**: Use the AskUserQuestion tool to probe the idea. Focus on:
-   - Non-obvious questions (not things already answered)
-   - Assumptions and unstated constraints
-   - Tradeoffs and concerns
-   - What could go wrong
-   - The "why" behind decisions
-
-3. **Go where it leads**: Follow tangents if they reveal something valuable. This isn't a checklist—it's a conversation.
-
-4. **Document as you go**: Don't defer writing to the end. Capture insights in the appropriate location:
-   - Research: `docs/workflow/research/` (semantic filenames)
-   - Discussion: `docs/workflow/discussion/{topic}.md`
-
-   Ask before documenting: "Shall I capture that?"
-
-5. **Commit frequently**: At natural breaks and before context refresh. Don't risk losing detail.
-
-6. **Exit when done**: The user decides when the interview is complete.
-
-## Question quality
-
-Aim for questions that:
-- The user hasn't already answered
-- Reveal hidden complexity
-- Surface concerns early
-- Challenge comfortable assumptions
-
-Avoid:
-- Restating what's already documented
-- Obvious surface-level questions
-- Leading questions that assume an answer