@juicesharp/rpiv-pi 0.5.0 → 0.6.0

package/README.md

@@ -145,6 +145,7 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 | `/rpiv-setup` | Install all sibling plugins in one go |
 | `/rpiv-update-agents` | Sync rpiv agent profiles: add new, update changed, remove stale |
 | `/advisor` | Configure advisor model and reasoning effort |
+| `/btw` | Ask a side question without polluting the main conversation |
 | `/todos` | Show current todo list |
 | `/web-search-config` | Set Brave Search API key |
 
@@ -180,6 +181,7 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 
 - **Web search** — run `/web-search-config` to set the Brave Search API key, or set the `BRAVE_SEARCH_API_KEY` environment variable
 - **Advisor** — run `/advisor` to select a reviewer model and reasoning effort
+- **Side questions** — type `/btw <question>` anytime (even mid-stream) to ask the primary model a one-off question; answer appears in a borderless bottom overlay and never enters the main conversation
 - **Agent concurrency** — `@tintinweb/pi-subagents` defaults to 4 concurrent agents; raise via `/agents → Settings → Max concurrency → 48` if skills stall on wide fan-outs
 - **Agent profiles** — editable at `<cwd>/.pi/agents/`; sync from bundled defaults with `/rpiv-update-agents` (overwrites rpiv-managed files, preserves your custom agents)
 

package/extensions/rpiv-core/siblings.ts

@@ -40,6 +40,11 @@ export const SIBLINGS: readonly SiblingPlugin[] = [
 		matches: /rpiv-advisor/i,
 		provides: "advisor tool + /advisor command",
 	},
+	{
+		pkg: "npm:@juicesharp/rpiv-btw",
+		matches: /rpiv-btw/i,
+		provides: "/btw side-question command",
+	},
 	{
 		pkg: "npm:@juicesharp/rpiv-web-tools",
 		matches: /rpiv-web-tools/i,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Skill-based development workflow for Pi Agent — discover, research, design, plan, implement, validate",
   "keywords": ["pi-package", "pi-extension", "rpiv", "skills", "workflow"],
   "license": "MIT",
@@ -28,6 +28,7 @@
     "@juicesharp/rpiv-ask-user-question": "*",
     "@juicesharp/rpiv-todo": "*",
     "@juicesharp/rpiv-advisor": "*",
+    "@juicesharp/rpiv-btw": "*",
     "@juicesharp/rpiv-web-tools": "*"
   }
 }

package/skills/explore/SKILL.md

@@ -22,37 +22,38 @@ I'll analyze the current codebase, generate solution options, and provide recomm
 
 Then wait for the user's request.
 
-## Steps to follow after receiving the request:
+## Steps
 
-1. **Read context files and understand the problem:**
-   - If user mentions tickets, research docs, or other files, read them FULLY first
-   - **IMPORTANT**: Use Read tool WITHOUT limit/offset parameters
-   - **CRITICAL**: Read these files in main context before invoking skills
-   - Extract requirements, constraints, and goals
-   - Identify what problem we're solving
+### Step 1: Read Mentioned Files
 
-2. **Generate candidates and dimensions:**
+- If user mentions tickets, research docs, or other files, read them FULLY first
+- **IMPORTANT**: Use Read tool WITHOUT limit/offset parameters
+- **CRITICAL**: Read these files in main context before invoking skills
+- Extract requirements, constraints, and goals
+- Identify what problem we're solving
 
-   **Generate 2–4 named candidates** from three sources, then merge into one shortlist:
+### Step 2: Generate Candidates and Dimensions
 
-   - **Ecosystem scan** — spawn `web-search-researcher` for any topic where the candidate space includes external libraries, frameworks, or services. Prompt it to return 2–4 named options with one-line "what it is" + canonical doc link per option. Skip only when the topic is wholly internal (e.g., "how to organize this service layer") and the orchestrator's design-space enumeration plus the user shortlist already cover the space.
-   - **Design-space enumeration** — orchestrator names abstract shapes from first principles when applicable (pub/sub vs direct-call vs event-bus; sync vs async; manual mapping vs auto-mapper). One-line "what it is" per shape.
-   - **User shortlist** — if the user pre-named candidates in the entry prompt ("compare TanStack Query vs SWR"), include those verbatim.
+**Generate 2–4 named candidates** from three sources, then merge into one shortlist:
 
-   Merge to 2–4 candidates total. Name each with a short noun phrase ("TanStack Query", "Direct event bus"). Deduplicate.
+- **Ecosystem scan** — spawn `web-search-researcher` for any topic where the candidate space includes external libraries, frameworks, or services. Prompt it to return 2–4 named options with one-line "what it is" + canonical doc link per option. Skip only when the topic is wholly internal (e.g., "how to organize this service layer") and the orchestrator's design-space enumeration plus the user shortlist already cover the space.
+- **Design-space enumeration** — orchestrator names abstract shapes from first principles when applicable (pub/sub vs direct-call vs event-bus; sync vs async; manual mapping vs auto-mapper). One-line "what it is" per shape.
+- **User shortlist** — if the user pre-named candidates in the entry prompt ("compare TanStack Query vs SWR"), include those verbatim.
 
-   **Default dimension list** (presented at Step 2.5; developer may drop irrelevant ones):
+Merge to 2–4 candidates total. Name each with a short noun phrase ("TanStack Query", "Direct event bus"). Deduplicate.
 
-   - **approach-shape** (hybrid) — what category of solution the candidate is, what core moving parts it requires.
-   - **precedent-fit** (codebase-anchored) — does the existing code already use this pattern; how many call sites would adopt the new option.
-   - **integration-risk** (codebase-anchored) — which existing seams the candidate would touch; what breaks if it lands.
-   - **migration-cost** (external-anchored for libraries; codebase-anchored for in-house code) — work to introduce the candidate plus work to remove the incumbent if there is one.
-   - **verification-cost** (codebase-anchored) — test/CI surface needed to make the candidate safe to adopt.
-   - **novelty** (external-anchored) — how recently the candidate emerged, ecosystem momentum, deprecation risk.
+**Default dimension list** (presented at Step 3; developer may drop irrelevant ones):
 
-   Hold the candidate set and default dimension list in working state for the Step 2.5 checkpoint. Do not dispatch fit agents yet.
+- **approach-shape** (hybrid) — what category of solution the candidate is, what core moving parts it requires.
+- **precedent-fit** (codebase-anchored) — does the existing code already use this pattern; how many call sites would adopt the new option.
+- **integration-risk** (codebase-anchored) — which existing seams the candidate would touch; what breaks if it lands.
+- **migration-cost** (external-anchored for libraries; codebase-anchored for in-house code) — work to introduce the candidate plus work to remove the incumbent if there is one.
+- **verification-cost** (codebase-anchored) — test/CI surface needed to make the candidate safe to adopt.
+- **novelty** (external-anchored) — how recently the candidate emerged, ecosystem momentum, deprecation risk.
 
-## Step 2.5: Candidate Checkpoint
+Hold the candidate set and default dimension list in working state for the Step 3 checkpoint. Do not dispatch fit agents yet.
+
+### Step 3: Candidate Checkpoint
 
 Present the candidate set and default dimensions to the developer before per-candidate fit dispatch.
 
@@ -74,251 +75,257 @@ Present the candidate set and default dimensions to the developer before per-can
 
 3. **Handle developer input:**
 
-   **"Proceed"**: lock the candidate × dimension set; advance to Step 3.
+   **"Proceed"**: lock the candidate × dimension set; advance to Step 4.
 
    **"Adjust candidates or dimensions"**: ask the follow-up free-text question with prefix `❓ Question:` — "Which candidates and dimensions should be added, dropped, or renamed?" — apply edits to the working set, re-present, and confirm again with the same three-option `ask_user_question`.
 
-   **"Re-generate candidates"**: ask the follow-up free-text question with prefix `❓ Question:` — "What should be different in candidate generation? (narrower/wider scope, different ecosystem, exclude approach X, …)" — return to Step 2 with the updated scope, then re-enter Step 2.5.
+   **"Re-generate candidates"**: ask the follow-up free-text question with prefix `❓ Question:` — "What should be different in candidate generation? (narrower/wider scope, different ecosystem, exclude approach X, …)" — return to Step 2 with the updated scope, then re-enter Step 3.
 
    Loop until "Proceed" is selected.
 
-3. **Per-candidate fit dispatch (parallel agents):**
+### Step 4: Per-Candidate Fit Dispatch (parallel agents)
 
-   For each confirmed candidate, dispatch up to two agents in parallel — total ≤ 2 × N agents:
+For each confirmed candidate, dispatch up to two agents in parallel — total ≤ 2 × N agents:
 
-   - **One `codebase-analyzer` per candidate** — when ≥1 kept dimension is codebase-anchored (precedent-fit, integration-risk, often migration-cost and verification-cost). The agent scores the candidate on every kept codebase-anchored dimension in a single pass, returning evidence per dimension with `file:line` references.
-   - **One `web-search-researcher` per candidate** — when ≥1 kept dimension is external-anchored (novelty, often migration-cost for libraries, approach-shape for ecosystem options). The agent scores the candidate on every kept external-anchored dimension in a single pass, returning evidence per dimension with doc/source links.
+- **One `codebase-analyzer` per candidate** — when ≥1 kept dimension is codebase-anchored (precedent-fit, integration-risk, often migration-cost and verification-cost). The agent scores the candidate on every kept codebase-anchored dimension in a single pass, returning evidence per dimension with `file:line` references.
+- **One `web-search-researcher` per candidate** — when ≥1 kept dimension is external-anchored (novelty, often migration-cost for libraries, approach-shape for ecosystem options). The agent scores the candidate on every kept external-anchored dimension in a single pass, returning evidence per dimension with doc/source links.
 
-   Skip either agent for a candidate when no dimension of that anchor-type was kept. Hybrid dimension `approach-shape` is scored by the orchestrator after both agents return, by combining their per-candidate findings.
+Skip either agent for a candidate when no dimension of that anchor-type was kept. Hybrid dimension `approach-shape` is scored by the orchestrator after both agents return, by combining their per-candidate findings.
 
-   **Per-candidate prompt shape** (use the same outer template, fill in candidate name and kept dimensions):
+**Per-candidate prompt shape** (use the same outer template, fill in candidate name and kept dimensions):
 
-   ```
-   Candidate: [name] — [one-line what it is]
-   Topic: [topic from Step 1]
+```
+Candidate: [name] — [one-line what it is]
+Topic: [topic from Step 1]
 
-   Score this single candidate on the following dimensions, each with concrete evidence ([file:line] for codebase, doc/source link for external). Report findings as one section per dimension.
+Score this single candidate on the following dimensions, each with concrete evidence ([file:line] for codebase, doc/source link for external). Report findings as one section per dimension.
 
-   Dimensions for this run:
-   - [dimension name] — [one-line of what to look for]
-   - ...
+Dimensions for this run:
+- [dimension name] — [one-line of what to look for]
+- ...
 
-   Do NOT compare against other candidates; another agent handles each one separately. Focus on depth of evidence for THIS candidate.
-   ```
+Do NOT compare against other candidates; another agent handles each one separately. Focus on depth of evidence for THIS candidate.
+```
+
+Wait for ALL agents to complete before proceeding.
+
+**Coverage check**: every (candidate × kept-dimension) cell is filled — by an agent's evidence or by an explicit `null` ("does not apply to this candidate"). Cells silently dropped indicate a missing dispatch — re-run that candidate's agent.
+
+### Step 5: Synthesize and Recommend
+
+- Cross-reference per-candidate findings — fill the candidate × dimension grid with evidence per cell.
+- Apply the fit filter qualitatively per candidate: a candidate "clears" when no kept dimension surfaces a blocking concern (integration-risk that breaks load-bearing seams, migration-cost that exceeds the topic's scope, verification-cost with no path to coverage).
+- **If ≥1 candidate clears the fit filter**: pick the strongest, document rationale with evidence, and explain why alternatives weren't chosen. Identify conditions that would change the recommendation.
+- **If every candidate fails the fit filter**: produce a "no-fit" recommendation — list each candidate's blocking dimension with evidence, recommend re-scoping the question or expanding the candidate pool, and set Step 7 frontmatter `confidence: low` and `status: blocked`.
+
+### Step 6: Determine Metadata and Filename
+
+- Filename format: `thoughts/shared/solutions/YYYY-MM-DD_HH-MM-SS_[topic].md`
+  - YYYY-MM-DD_HH-MM-SS: Current date and time (e.g., 2025-10-11_14-30-22)
+  - [topic]: Brief kebab-case description
+- Repository name: from git root basename, or current directory basename if not a git repo
+- Use the git branch and commit from the git context injected at the start of the session (or run `git branch --show-current` / `git rev-parse --short HEAD` directly)
+- Researcher: use the User from the git context injected at the start of the session (fallback: "unknown")
+- If metadata unavailable: use "unknown" for commit/branch
+
+### Step 7: Generate Solutions Document
+
+- Use the metadata gathered in step 6
+- Structure the document with YAML frontmatter followed by content:
+
+  ```markdown
+  ---
+  date: [Current date and time with timezone in ISO format]
+  researcher: [Researcher name]
+  git_commit: [Current commit hash]
+  branch: [Current branch name]
+  repository: [Repository name]
+  topic: "[Feature/Problem]"
+  confidence: high | medium | low
+  complexity: low | medium | high
+  status: ready | awaiting_input | blocked
+  tags: [solutions, component-names]
+  last_updated: [Current date in YYYY-MM-DD format]
+  last_updated_by: [Researcher name]
+  ---
 
-   Wait for ALL agents to complete before proceeding.
-
-   **Coverage check**: every (candidate × kept-dimension) cell is filled — by an agent's evidence or by an explicit `null` ("does not apply to this candidate"). Cells silently dropped indicate a missing dispatch — re-run that candidate's agent.
-
-4. **Synthesize and recommend:**
+  # Solution Analysis: [Feature/Problem]
 
-   - Cross-reference per-candidate findings — fill the candidate × dimension grid with evidence per cell.
-   - Apply the fit filter qualitatively per candidate: a candidate "clears" when no kept dimension surfaces a blocking concern (integration-risk that breaks load-bearing seams, migration-cost that exceeds the topic's scope, verification-cost with no path to coverage).
-   - **If ≥1 candidate clears the fit filter**: pick the strongest, document rationale with evidence, and explain why alternatives weren't chosen. Identify conditions that would change the recommendation.
-   - **If every candidate fails the fit filter**: produce a "no-fit" recommendation — list each candidate's blocking dimension with evidence, recommend re-scoping the question or expanding the candidate pool, and set Step 6 frontmatter `confidence: low` and `status: blocked`.
-
-5. **Determine metadata and filename:**
-   - Filename format: `thoughts/shared/solutions/YYYY-MM-DD_HH-MM-SS_[topic].md`
-     - YYYY-MM-DD_HH-MM-SS: Current date and time (e.g., 2025-10-11_14-30-22)
-     - [topic]: Brief kebab-case description
-   - Repository name: from git root basename, or current directory basename if not a git repo
-   - Use the git branch and commit from the git context injected at the start of the session (or run `git branch --show-current` / `git rev-parse --short HEAD` directly)
-   - Researcher: use the User from the git context injected at the start of the session (fallback: "unknown")
-   - If metadata unavailable: use "unknown" for commit/branch
+  **Date**: [Current date and time with timezone from step 6]
+  **Researcher**: [Researcher name from step 6]
+  **Git Commit**: [Current commit hash from step 6]
+  **Branch**: [Current branch name from step 6]
+  **Repository**: [Repository name]
 
-6. **Generate solutions document:**
-   - Use the metadata gathered in step 5
-   - Structure the document with YAML frontmatter followed by content:
-     ```markdown
-     ---
-     date: [Current date and time with timezone in ISO format]
-     researcher: [Researcher name]
-     git_commit: [Current commit hash]
-     branch: [Current branch name]
-     repository: [Repository name]
-     topic: "[Feature/Problem]"
-     confidence: high | medium | low
-     complexity: low | medium | high
-     status: ready | awaiting_input | blocked
-     tags: [solutions, component-names]
-     last_updated: [Current date in YYYY-MM-DD format]
-     last_updated_by: [Researcher name]
-     ---
+  ## Research Question
+  [Original user query]
 
-     # Solution Analysis: [Feature/Problem]
+  ## Summary
+  **Problem**: [What we're solving]
+  **Recommended**: [Option name] - [One sentence why]
+  **Effort**: [Low/Med/High] ([N days])
+  **Confidence**: [High/Med/Low]
 
-     **Date**: [Current date and time with timezone from step 5]
-     **Researcher**: [Researcher name from step 5]
-     **Git Commit**: [Current commit hash from step 5]
-     **Branch**: [Current branch name from step 5]
-     **Repository**: [Repository name]
+  ## Problem Statement
 
-     ## Research Question
-     [Original user query]
+  **Requirements:**
+  - [Requirement 1]
+  - [Requirement 2]
 
-     ## Summary
-     **Problem**: [What we're solving]
-     **Recommended**: [Option name] - [One sentence why]
-     **Effort**: [Low/Med/High] ([N days])
-     **Confidence**: [High/Med/Low]
+  **Constraints:**
+  - [Hard constraint - must respect]
+  - [Soft constraint - should consider]
 
-     ## Problem Statement
+  **Success criteria:**
+  - [What "done" looks like]
 
-     **Requirements:**
-     - [Requirement 1]
-     - [Requirement 2]
+  ## Current State
 
-     **Constraints:**
-     - [Hard constraint - must respect]
-     - [Soft constraint - should consider]
+  **Existing implementation:**
+  [What exists with file:line references]
 
-     **Success criteria:**
-     - [What "done" looks like]
+  **Relevant patterns:**
+  - [Pattern 1]: `file.ext:line` - Used in [N] places
+  - [Pattern 2]: `file.ext:line` - Used in [N] places
 
-     ## Current State
+  **Integration points:**
+  - `file.ext:line` - [Where feature hooks in]
+  - `file.ext:line` - [Another integration point]
 
-     **Existing implementation:**
-     [What exists with file:line references]
+  ## Solution Options
 
-     **Relevant patterns:**
-     - [Pattern 1]: `file.ext:line` - Used in [N] places
-     - [Pattern 2]: `file.ext:line` - Used in [N] places
+  ### Option 1: [Name]
+  **How it works:**
+  [2-3 sentence description + implementation approach]
 
-     **Integration points:**
-     - `file.ext:line` - [Where feature hooks in]
-     - `file.ext:line` - [Another integration point]
+  **Pros:**
+  - [Advantage with evidence from codebase]
+  - [Advantage with evidence]
 
-     ## Solution Options
+  **Cons:**
+  - [Disadvantage with impact]
 
-     ### Option 1: [Name]
-     **How it works:**
-     [2-3 sentence description + implementation approach]
+  **Complexity:** [Low/Med/High] (~[N] days)
+  - Files to create: [N] (~[X] lines)
+  - Files to modify: [N] (~[X] lines)
+  - Risk level: [Low/Med/High]
 
-     **Pros:**
-     - [Advantage with evidence from codebase]
-     - [Advantage with evidence]
+  ### Option 2: [Alternative Name]
+  [Same structure as Option 1]
 
-     **Cons:**
-     - [Disadvantage with impact]
+  ### Option 3: [Another Alternative]
+  [Same structure as Option 1]
 
-     **Complexity:** [Low/Med/High] (~[N] days)
-     - Files to create: [N] (~[X] lines)
-     - Files to modify: [N] (~[X] lines)
-     - Risk level: [Low/Med/High]
+  ## Comparison
 
-     ### Option 2: [Alternative Name]
-     [Same structure as Option 1]
+  | Criteria | Option 1 | Option 2 | Option 3 |
+  |----------|----------|----------|----------|
+  | Complexity | [L/M/H] | [L/M/H] | [L/M/H] |
+  | Codebase fit | [H/M/L] | [H/M/L] | [H/M/L] |
+  | Risk | [L/M/H] | [L/M/H] | [L/M/H] |
 
-     ### Option 3: [Another Alternative]
-     [Same structure as Option 1]
+  ## Recommendation
 
-     ## Comparison
+  <!-- Render exactly ONE of the two blocks below, based on Step 5's fit-filter outcome. -->
 
-     | Criteria | Option 1 | Option 2 | Option 3 |
-     |----------|----------|----------|----------|
-     | Complexity | [L/M/H] | [L/M/H] | [L/M/H] |
-     | Codebase fit | [H/M/L] | [H/M/L] | [H/M/L] |
-     | Risk | [L/M/H] | [L/M/H] | [L/M/H] |
+  **(A) When ≥1 candidate clears the fit filter:**
 
-     ## Recommendation
+  **Selected:** [Option N]
 
-     <!-- Render exactly ONE of the two blocks below, based on Step 4's fit-filter outcome. -->
+  **Rationale:**
+  - [Key reason with evidence]
+  - [Key reason with evidence]
+  - ...
 
-     **(A) When ≥1 candidate clears the fit filter:**
+  **Why not alternatives:**
+  - Option X: [Reason]
 
-     **Selected:** [Option N]
+  **Trade-offs:**
+  - Accepting [limitation] for [benefit]
 
-     **Rationale:**
-     - [Key reason with evidence]
-     - [Key reason with evidence]
-     - ...
+  **Implementation approach:**
+  1. [Phase 1] - [What to build]
+  2. ...
 
-     **Why not alternatives:**
-     - Option X: [Reason]
+  **Integration points:**
+  - `file.ext:line` - [Specific change]
+  - `file.ext:line` - [Specific change]
 
-     **Trade-offs:**
-     - Accepting [limitation] for [benefit]
+  **Patterns to follow:**
+  - [Pattern]: `file.ext:line`
 
-     **Implementation approach:**
-     1. [Phase 1] - [What to build]
-     2. ...
+  **Risks:**
+  - [Risk]: [Mitigation]
 
-     **Integration points:**
-     - `file.ext:line` - [Specific change]
-     - `file.ext:line` - [Specific change]
+  **(B) When every candidate fails the fit filter:**
 
-     **Patterns to follow:**
-     - [Pattern]: `file.ext:line`
+  **No-fit:** every candidate surfaced a blocking concern on at least one kept dimension.
 
-     **Risks:**
-     - [Risk]: [Mitigation]
+  **Per-candidate blockers:**
+  - [Option 1]: [blocking dimension] — [evidence with file:line or doc link]
+  - [Option 2]: [blocking dimension] — [evidence]
+  - ...
 
-     **(B) When every candidate fails the fit filter:**
+  **Recommended next step:**
+  - [Re-scope the question] — [how the topic should narrow/widen so candidates can clear]
+  - OR [Expand the candidate pool] — [what new candidate sources to enumerate; e.g., named ecosystem option not surfaced by Step 2]
 
-     **No-fit:** every candidate surfaced a blocking concern on at least one kept dimension.
+  **Frontmatter overrides:** set `confidence: low` and `status: blocked`.
 
-     **Per-candidate blockers:**
-     - [Option 1]: [blocking dimension] — [evidence with file:line or doc link]
-     - [Option 2]: [blocking dimension] — [evidence]
-     - ...
+  ## Scope Boundaries
+  - [What we're building]
+  - [What we're NOT doing]
 
-     **Recommended next step:**
-     - [Re-scope the question] — [how the topic should narrow/widen so candidates can clear]
-     - OR [Expand the candidate pool] — [what new candidate sources to enumerate; e.g., named ecosystem option not surfaced by Step 2]
+  ## Testing Strategy
 
-     **Frontmatter overrides:** set `confidence: low` and `status: blocked`.
+  **Unit tests:**
+  - [Key test scenario 1]
+  - ...
 
-     ## Scope Boundaries
-     - [What we're building]
-     - [What we're NOT doing]
+  **Integration tests:**
+  - [End-to-end scenario 1]
+  - ...
 
-     ## Testing Strategy
+  **Manual verification:**
+  - [ ] [Manual test 1]
+  - [ ] ...
 
-     **Unit tests:**
-     - [Key test scenario 1]
-     - ...
+  ## Open Questions
+  **Resolved during research:**
+  - [Question that was answered] - [Answer with evidence from file:line]
 
-     **Integration tests:**
-     - [End-to-end scenario 1]
-     - ...
+  **Requires user input:**
+  - [Business or design question] - [Default assumption for planning]
 
-     **Manual verification:**
-     - [ ] [Manual test 1]
-     - [ ] ...
+  **Blockers:**
+  - [Critical unknown that prevents implementation] - [How to unblock]
 
-     ## Open Questions
-     **Resolved during research:**
-     - [Question that was answered] - [Answer with evidence from file:line]
+  ## References
 
-     **Requires user input:**
-     - [Business or design question] - [Default assumption for planning]
+  - `thoughts/shared/research/[file].md` - [Context]
+  - `src/file.ext:line` - [Similar implementation]
+  - `thoughts/shared/[file].md` - [Historical decision]
+  ```
 
-     **Blockers:**
-     - [Critical unknown that prevents implementation] - [How to unblock]
+### Step 8: Present Findings
 
-     ## References
+- Present concise summary with clear recommendation
+- Highlight key integration points
+- Ask if they want to proceed to /skill:design with the chosen option or need clarification
 
-     - `thoughts/shared/research/[file].md` - [Context]
-     - `src/file.ext:line` - [Similar implementation]
-     - `thoughts/shared/[file].md` - [Historical decision]
-     ```
+### Step 9: Handle Follow-up Questions
 
-7. **Present findings:**
-   - Present concise summary with clear recommendation
-   - Highlight key integration points
-   - Ask if they want to proceed to /skill:design with the chosen option or need clarification
+- If user has questions, append to same document
+- Update frontmatter: `last_updated` and `last_updated_by`
+- Add section: `## Follow-up Analysis [timestamp]`
+- Spawn additional agents as needed
 
-8. **Handle follow-up questions:**
-   - If user has questions, append to same document
-   - Update frontmatter: `last_updated` and `last_updated_by`
-   - Add section: `## Follow-up Analysis [timestamp]`
-   - Spawn additional agents as needed
+## Important Notes
 
-## Important notes:
 - Always use parallel Agent tool calls to maximize efficiency and minimize context usage
 - Always spawn fresh research to validate current state - never rely on old research docs as source of truth
 - Old research documents can provide historical context but must be validated against current code
-- Generate 2-4 named candidates in Step 2; confirm them with the developer at Step 2.5 before per-candidate fit dispatch
+- Generate 2-4 named candidates in Step 2; confirm them with the developer at Step 3 before per-candidate fit dispatch
 - Web-search-researcher is a first-class Step 2 agent for ecosystem candidate-source — skip only when the topic is wholly internal and design-space enumeration plus user shortlist cover the space
 - Per-candidate fit dispatch caps at two agents per candidate (one codebase-analyzer, one web-search-researcher) — skip either when no dimension of its anchor-type was kept
 - Solutions documents should be self-contained with all necessary context
@@ -332,7 +339,7 @@ Present the candidate set and default dimensions to the developer before per-can
 - **File reading**: Always read mentioned files FULLY (no limit/offset) before invoking skills
 - **Critical ordering**: Follow the numbered steps exactly
   - ALWAYS read mentioned files first before invoking skills (step 1)
-  - ALWAYS generate candidates and run the Step 2.5 checkpoint before per-candidate dispatch (steps 2 → 2.5 → 3)
-  - ALWAYS wait for all per-candidate agents to complete before synthesizing (step 3)
-  - ALWAYS gather metadata before writing the document (step 5 before step 6)
+  - ALWAYS generate candidates and run the Step 3 checkpoint before per-candidate dispatch (steps 2 → 3 → 4)
+  - ALWAYS wait for all per-candidate agents to complete before synthesizing (step 4)
+  - ALWAYS gather metadata before writing the document (step 6 before step 7)
   - NEVER write the solutions document with placeholder values