@juicesharp/rpiv-pi 1.8.0 → 1.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.",
   "keywords": [
     "pi-package",

package/skills/annotate-guidance/SKILL.md

@@ -5,13 +5,13 @@ argument-hint: [target-directory]
 allowed-tools: Agent, Read, Write, Glob, Grep
 ---
 
-# Annotate Project
+# Annotate Guidance
 
 You are tasked with generating architecture guidance files for a brownfield project. You will map the project structure, auto-detect its architecture, analyze each architectural layer, and batch-write compact architecture.md files under `.rpiv/guidance/` mirroring the project's directory structure.
 
-## Initial Setup:
+## Input
 
-Use the current working directory as the target project by default. If the user provides a specific directory path as an argument, use that instead.
+`$ARGUMENTS` — optional target directory. Defaults to the current working directory.
 
 ## Steps to follow:
 

package/skills/annotate-inline/SKILL.md

@@ -5,13 +5,13 @@ argument-hint: [target-directory]
 allowed-tools: Agent, Read, Write, Glob, Grep
 ---
 
-# Annotate Project
+# Annotate Inline
 
 You are tasked with generating CLAUDE.md files across a brownfield project. You will map the project structure, auto-detect its architecture, analyze each architectural layer, and batch-write compact CLAUDE.md files at the root and relevant subdirectories.
 
-## Initial Setup:
+## Input
 
-Use the current working directory as the target project by default. If the user provides a specific directory path as an argument, use that instead.
+`$ARGUMENTS` — optional target directory. Defaults to the current working directory.
 
 ## Steps to follow:
 

package/skills/blueprint/SKILL.md

@@ -1,28 +1,26 @@
 ---
 name: blueprint
 description: Plan complex features by decomposing them into vertical slices (one slice equals one phase) with developer micro-checkpoints between phases, producing an implement-ready phased plan in thoughts/shared/plans/. Use for complex multi-component features touching 6+ files across multiple layers when iterative review between slices is valuable. Requires a research artifact or a solutions artifact (from explore). Prefer blueprint over plan when mid-flight micro-checkpoints matter, and prefer plan when a straightforward phased breakdown is enough.
-argument-hint: [research artifact path]
+argument-hint: "[research artifact path]"
 ---
 
-# Plan
+# Blueprint
 
 You are tasked with planning how code will be shaped for a feature or change AND emitting an implement-ready phased plan. Decompose the feature into vertical slices (one slice = one phase), generate code slice-by-slice with developer micro-checkpoints between slices, and write the final artifact directly into `thoughts/shared/plans/` for `/skill:implement` to consume.
 
-**How it works**:
-- Read input and key source files into context (Step 1)
-- Spawn targeted research agents for depth analysis (Step 2)
-- Identify ambiguities — triage into simple decisions and genuine ambiguities (Step 3)
-- Holistic self-critique — review the combined design for gaps and contradictions (Step 4)
-- Developer checkpoint — resolve genuine ambiguities one at a time (Step 5)
-- Decompose into vertical slices holistically before generating code (Step 6)
-- Generate code slice-by-slice with developer micro-checkpoints (Step 7)
-- Verify cross-slice integration consistency (Step 8 — internal, folded into final 7.3)
-- Finalize the design artifact (Step 9)
-- Review and iterate with the developer (Step 10)
+## Input
+
+`$ARGUMENTS` — path to a research artifact (`thoughts/shared/research/*.md`) or a solutions artifact (`thoughts/shared/solutions/*.md`).
+
+## Flow
+
+1. Input → 2. Research → 3. Dimension sweep → 4. Self-critique → 5. Checkpoint → 6. Decompose → 7. Generate slices → 8. Integration verify → 9. Finalize → 10. Independent review → 11. Triage & iterate → 12. Follow-ups
 
 The final artifact is implement-ready.
 
-## Step 1: Input Handling
+## Steps
+
+### Step 1: Input Handling
 
 When this command is invoked:
 
@@ -47,7 +45,7 @@ When this command is invoked:
 
 2. **Read any additional files mentioned** — tickets, related designs, existing implementations. Read them FULLY before proceeding.
 
-## Step 2: Targeted Research
+### Step 2: Targeted Research
 
 This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to follow) not BREADTH (where things are).
 
@@ -76,7 +74,7 @@ This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to
    - Note assumptions that need verification
    - Determine true scope based on codebase reality
 
-## Step 3: Identify Ambiguities — Dimension Sweep
+### Step 3: Identify Ambiguities — Dimension Sweep
 
 Walk Step 2 findings, inherited research Q/As, and carried Open Questions through six architectural dimensions that map 1:1 to the plan artifact's section coverage — the sweep guarantees downstream completeness. Add **migration** as a seventh dimension only if the feature changes persisted schema.
 
@@ -91,7 +89,7 @@ For each dimension, classify findings as **simple decisions** (one valid option,
 
 **Pre-validate every option** before queuing it against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence. **Coverage check**: every Step 2 file read appears in at least one decision or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not).
 
-## Step 4: Holistic Self-Critique
+### Step 4: Holistic Self-Critique
 
 Before presenting ambiguities to the developer, review the combined design picture holistically. Step 3 triages findings individually — this step checks whether they fit together as a coherent whole.
 
@@ -111,7 +109,7 @@ Before presenting ambiguities to the developer, review the combined design pictu
 - Issues that need developer input: add as new genuine ambiguities to the Step 5 checkpoint queue.
 - If no issues found: proceed to Step 5 with the existing ambiguity set.
 
-## Step 5: Developer Checkpoint
+### Step 5: Developer Checkpoint
 
 Use the grounded-questions-one-at-a-time pattern. Use a **❓ Question:** prefix so the developer knows their input is needed. Each question must:
 - Reference real findings with `file:line` evidence
@@ -171,7 +169,7 @@ Files: {N} new, {M} modified
 
 Use the `ask_user_question` tool to confirm before proceeding. Question: "{Summary from design brief above}. Ready to proceed to decomposition?". Header: "Design". Options: "Proceed (Recommended)" (Decompose into vertical slices, then generate code slice-by-slice); "Adjust decisions" (Revisit one or more architectural decisions above); "Change scope" (Add or remove items from the building/not-building lists).
 
-## Step 6: Feature Decomposition
+### Step 6: Feature Decomposition
 
 After the design summary is confirmed, decompose the feature into vertical slices. Each slice is a self-contained unit: types + implementation + wiring for one concern.
 
@@ -237,7 +235,7 @@ After the design summary is confirmed, decompose the feature into vertical slice
    - **NEW files**: `#### N. path/to/file.ext` + `**File**: path` + `**Changes**: NEW — {purpose}` + empty code fence (filled with full implementation in Step 7.4)
    - **MODIFY files**: `#### N. path/to/file.ext:line-range` + `**File**: path` + `**Changes**: MODIFY — {summary}` + empty code fence (filled with only the modified code in Step 7.4 — no "Current" block, the original is on disk)
 
-## Step 7: Generate Slices (Iterative)
+### Step 7: Generate Slices (Iterative)
 
 Generate code one slice at a time. Each slice sees the fixed code from all previous slices.
 
@@ -245,7 +243,7 @@ Generate code one slice at a time. Each slice sees the fixed code from all previ
 
 **For each slice in the decomposition (sequential order):**
 
-### 7.1. Generate slice code (internal)
+#### 7.1. Generate slice code (internal)
 
 Generate complete, copy-pasteable code for every file in this slice — but **hold it for the artifact, do NOT present full code to the developer**. The developer sees a condensed review in 7.3; the full code goes into the artifact in 7.4.
 
@@ -260,7 +258,7 @@ No pseudocode, no TODOs, no placeholders — the code must be copy-pasteable by
 
 **Context grounding** (after slice 2): Before generating, re-read the artifact's prior `## Phase N` sections for files this slice touches (a file may appear in earlier phases; if so, this phase extends or revisits it). The artifact is the source of truth — generate code that extends what's already emitted, not what you remember from conversation.
 
-### 7.2. Verify slice
+#### 7.2. Verify slice
 
 Mandatory for every slice — no skipping, no shortcuts. Dispatch the `slice-verifier` agent with:
 - `artifact_path`: the Step-6 Write `file_path` (contains the skeleton plus locked prior phases; the current slice's code fence is still empty per 7.1/7.4 timing)
@@ -275,7 +273,7 @@ The agent emits a 3-row summary (`Decisions / Cross-slice / Research`). On any V
 
 Never proceed to 7.3 with a VIOLATION absent from the presentation.
 
-### 7.3. Developer micro-checkpoint
+#### 7.3. Developer micro-checkpoint
 
 Present a **condensed review** of the slice — NOT the full generated code. The developer reviews the design shape, not every line. For each file in the slice, show:
 
@@ -294,7 +292,7 @@ Use the `ask_user_question` tool to confirm. Question: "Slice {N/M}: {slice name
 
 **Checkpoint cadence**: One slice per checkpoint. Present each slice individually, regardless of slice count.
 
-### 7.4. Incorporate feedback
+#### 7.4. Incorporate feedback
 
 **Approve**: Lock this slice's code and **Edit the artifact immediately**:
 1. For each file in this slice, Edit the skeleton artifact to replace the empty code fence under that file's `#### N. path/...` subsection inside this slice's `## Phase N: {slice name}` section with the full generated code from 7.1
@@ -325,7 +323,7 @@ Update decomposition (add/remove/reorder remaining slices) and confirm before co
 
 **Revisit a decision**: Re-run Step 5 for the flagged ambiguity (one question). If decomposition is unaffected, update `## Decisions` and resume 7.1. If affected, cascade like Rethink — for each invalidated approved phase, ask reopen vs. annotate Plan History, then update remaining slices. Re-run 7.2 before re-presenting 7.3; artifact untouched until approval.
 
-## Step 8: Integration Verification (internal)
+### Step 8: Integration Verification (internal)
 
 Runs during the final slice's 7.2 — no separate developer round-trip. Result feeds the final 7.3 question text.
 
@@ -333,7 +331,7 @@ Runs during the final slice's 7.2 — no separate developer round-trip. Result f
 2. **Constraint check**: every `## Verification Notes` and Precedent & Lesson entry from research is satisfied somewhere in the generated code.
 3. **Emit summary** for final 7.3: `OK` or `violations: {brief}`. No `ask_user_question` here — Step 7.3 absorbs the approval.
 
-## Step 9: Finalize Plan Artifact
+### Step 9: Finalize Plan Artifact
 
 The artifact was created as a skeleton in Step 6 and filled progressively in Step 7.4 (code fences + Success Criteria). This step verifies and flips status.
 
@@ -353,7 +351,7 @@ The artifact was created as a skeleton in Step 6 and filled progressively in Ste
    - **NEW files**: `#### N. path/to/file.ext` + `**File**` + `**Changes**: NEW — {purpose}` + full implementation code block
    - **MODIFY files**: `#### N. path/to/file.ext:line-range` + `**File**` + `**Changes**: MODIFY — {summary}` + code block with only the modified/added code (no "Current" block — the original is on disk, implement reads it)
 
-## Step 10: Independent Plan Review
+### Step 10: Independent Plan Review
 
 After Step 9 finalizes the artifact, dispatch an independent review subagent
 to walk every Phase code fence against the live codebase. The subagent runs
@@ -362,7 +360,7 @@ criticism > generation asymmetry plus fresh-context isolation. Inherits the
 orchestrator's model (no model upgrade required); the value comes from the
 fresh dispatch, not from a stronger model.
 
-### 10.1. Dispatch the artifact-reviewer subagent
+#### 10.1. Dispatch the artifact-reviewer subagent
 
 Reuse the exact `file_path` string passed to `Write` at Step 6 — the runtime already resolved it for this platform; do not rebuild it from `pwd`. `ls` to verify it still exists; abort dispatch on miss.
 
@@ -376,7 +374,7 @@ Review the finalized plan against the live codebase at HEAD. Walk every Phase co
 })
 ```
 
-### 10.2. Persist the review table to the artifact
+#### 10.2. Persist the review table to the artifact
 
 The agent returns a markdown table with columns `plan-loc | codebase-loc | severity | dimension | finding | recommendation`. Append it to the plan artifact as a new section, with a `resolution` column appended (initially blank, filled progressively at Step 11):
 
@@ -394,7 +392,7 @@ _Independent post-finalization review by artifact-reviewer subagent. Findings tr
 
 If the agent emits zero rows, still emit the section with a single line: `_No findings — artifact-reviewer cleared the artifact._`. Persistence is mandatory regardless of finding count — the section is the durable audit trail.
 
-### 10.3. Tally findings for Step 11's prompt
+#### 10.3. Tally findings for Step 11's prompt
 
 Count rows by severity. Store the counts in main context for Step 11's developer prompt:
 
@@ -404,7 +402,7 @@ Count rows by severity. Store the counts in main context for Step 11's developer
 
 Do NOT auto-apply any finding. The orchestrator never makes the apply / defer / dismiss judgment alone — that lives with the developer at Step 11. The reviewer's role is to surface; the developer's role is to triage.
 
-### 10.4. Failure handling
+#### 10.4. Failure handling
 
 If artifact-reviewer errors out (subprocess crash, malformed output, timeout):
 - Skip Step 10's findings; do not block on the failure.
@@ -414,7 +412,7 @@ If artifact-reviewer errors out (subprocess crash, malformed output, timeout):
 
 The developer review path at Step 11 absorbs the cost — that is how planning worked before this step existed.
 
-## Step 11: Review & Iterate
+### Step 11: Review & Iterate
 
 1. **Triage artifact-reviewer findings first** (skip if Step 10 returned no findings):
 
@@ -459,7 +457,7 @@ The developer review path at Step 11 absorbs the cost — that is how planning w
    > 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.
    ```
 
-## Step 12: Handle Follow-ups
+### Step 12: Handle Follow-ups
 
 - **Edit in-place.** Use the Edit tool to update the plan artifact directly — phase code stays one source of truth.
 - **Bump frontmatter.** Update `last_updated` + `last_updated_by`; set `last_updated_note: "Updated <brief description>"`.

package/skills/changelog/SKILL.md

@@ -9,9 +9,9 @@ allowed-tools: Bash(git *), Read, Edit
 
 You are tasked with regenerating the `## [Unreleased]` section of every affected `CHANGELOG.md` in the repository so it reflects all change since the last release tag — committed and uncommitted alike.
 
-## Range hint
+## Input
 
-`$ARGUMENTS` (empty/literal → range starts at the last release tag from `git describe --tags --abbrev=0`)
+`$ARGUMENTS` — optional `--since <ref>` flag. Empty/literal → range starts at the last release tag from `git describe --tags --abbrev=0`.
 
 ## Workflow
 
@@ -30,7 +30,7 @@ You are tasked with regenerating the `## [Unreleased]` section of every affected
 
 ## Step 2: Determine the change range
 
-1. Parse `$ARGUMENTS` for a `--since <ref>` flag. If absent, set `SINCE=$(git describe --tags --abbrev=0)`.
+1. Parse the input for a `--since <ref>` flag. If absent, set `SINCE=$(git describe --tags --abbrev=0)`.
 2. The range is `$SINCE..HEAD` for committed changes, plus the current uncommitted+staged working tree.
 
 ## Step 3: Determine each CHANGELOG's scope, then collect commits + uncommitted hunks

package/skills/code-review/SKILL.md

@@ -6,25 +6,23 @@ argument-hint: "[scope]"
 
 # Code Review
 
-Scope: $ARGUMENTS
-
 Review changes across **Quality**, **Security**, **Dependencies** lenses with optional advisor adjudication. Valid scopes: `commit` | `staged` | `working` | hash | `A..B` | PR branch. **Empty scope defaults to feature-branch-vs-default-branch first-parent review** (default branch auto-detected; see Step 1).
 
-**How it works**:
-- Step 1 — resolve scope, read diff (with `-U30` context), derive flags, build semantic file map
-- Step 2 — dispatch Wave-1: integration + precedents + (deps/CVE) + (peer-mirror); integration & peer-mirror gate Wave-2, precedents gates Step 5
-- Step 3 — dispatch Wave-2: Quality + Security lenses, file-oriented
-- Step 4 — dispatch Wave-3: Predicate-Trace + Interaction Sweep + Gap-Finder, all gated
-- Step 5 — reconcile via advisor or inline dimension-sweep (blocks on precedents)
-- Step 6 — verify findings: re-read each cited file:line; drop/demote unverified
-- Step 7 — write artifact
-- Steps 8–9 — present and handle follow-ups
+## Input
+
+`$ARGUMENTS` — scope: `commit` | `staged` | `working` | a commit hash | `A..B` range | PR branch name. Empty defaults to feature-branch-vs-default-branch (first-parent).
+
+## Flow
+
+1. Input → 2. Wave-1 dispatch → 3. Wave-2 dispatch → 4. Wave-3 dispatch → 5. Reconcile → 6. Verify → 7. Write artifact → 8. Present → 9. Follow-ups
 
 **File-orientation contract**: agents reason about *files* as coherent units. Hunks are evidence *within* a file's analysis, never the unit of analysis. The `-U30` patch (Step 1) inlines function-level context so agents rarely need extra `Read` calls.
 
 Every Wave-2 agent prompt contains EXACTLY: (a) `Known Context:` followed by the Discovery Map verbatim, and (b) the literal string `.git/code-review-patch.diff` as the patch path. Nothing else from Wave-1 outputs — NOT the raw integration-scanner dump, NOT precedent-locator output, NOT Dependencies/CVE output. See "Wave-2 context isolation" in Step 3 for the failure mode when this is violated. Wave-1 agents that do not consume the Discovery Map (precedents, dependencies, CVE) get `ChangedFiles` / manifest-diff only.
 
-## Step 1: Resolve Scope and Assemble the Diff
+## Steps
+
+### Step 1: Resolve Scope and Assemble the Diff
 
 1. **Detect default branch**: `DEFAULT_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')`. Fallback: probe `main` then `master` (`git rev-parse --verify --quiet <name>`); if neither resolves, ask the user which branch is the integration target before proceeding. Use `$DEFAULT_BRANCH` wherever the parser below says `<default>`.
 
@@ -67,7 +65,7 @@ Every Wave-2 agent prompt contains EXACTLY: (a) `Known Context:` followed by the
 
      Drop a pair only when the peer doesn't exist at HEAD, no heuristic matches, or both files were added in this diff. Empty list ⇒ skip the peer-mirror agent. Co-modified peers are KEPT — the agent Reads them at HEAD (post-diff tree state), so any invariant present at HEAD counts as peer evidence regardless of whether the peer was edited in this diff.
 
-## Step 2: Dispatch Wave-1 — Integration + Precedents + Deps/CVE + Peer-Mirror
+### Step 2: Dispatch Wave-1 — Integration + Precedents + Deps/CVE + Peer-Mirror
 
 Spawn ALL of the following in parallel at T=0 in a **single message with multiple Agent tool calls**. Do NOT wait for integration-scanner before dispatching precedents / dependencies / CVE — they do not consume Discovery-Map output, only `ChangedFiles` and the manifest diff (both orchestrator-produced in Step 1).
 
@@ -117,7 +115,7 @@ While these agents run, the orchestrator produces the rest of the Discovery Map
 **Synthesize the Discovery Map** — a compact block that Wave-2 agents receive verbatim as `Known Context`. Each file line carries a *role tag* and a *symbols-touched hint*; files are clustered by shared directory prefix so agents orient without re-reading the patch.
 
 ```
-## Discovery Map
+#### Discovery Map
 
 Review type: {ReviewType}
 Scope: {scope argument}
@@ -150,9 +148,9 @@ Peer mirrors: {peer-mirror agent output verbatim — Missing/Diverged rows only;
 
 **Symbols-touched hint**: extract top 1–3 top-level definitions from the diff's `+` lines using a heuristic appropriate to the file's language (class/function/def/fn/struct/trait/interface/type/export). Cap at ~80 chars. Leave blank if ambiguous — orientation, not completeness.
 
-## Step 3: Dispatch Wave-2 — Quality + Security Lenses
+### Step 3: Dispatch Wave-2 — Quality + Security Lenses
 
-Spawn Quality + Security in parallel using the Agent tool. Each receives the `## Discovery Map` block inline as `Known Context` above its task, and a pointer to `.git/code-review-patch.diff` for the diff itself. Precedents / Dependencies / CVE are already running from Wave-1 — do NOT re-dispatch them here; the prompts below document what those Wave-1 agents received, they are not re-issued.
+Spawn Quality + Security in parallel using the Agent tool. Each receives the Discovery Map block inline as `Known Context` above its task, and a pointer to `.git/code-review-patch.diff` for the diff itself. Precedents / Dependencies / CVE are already running from Wave-1 — do NOT re-dispatch them here; the prompts below document what those Wave-1 agents received, they are not re-issued.
 
 **Wave-2 context isolation (LOAD-BEARING — violations cause silent quality collapse)**: Each Wave-2 agent receives EXACTLY two things, nothing else: (1) the Discovery Map (digested form) and (2) the literal path string `.git/code-review-patch.diff`.
 
@@ -251,7 +249,7 @@ Spawn Quality + Security in parallel using the Agent tool. Each receives the `##
 
 **Wait for Quality + Security to complete** before proceeding. Precedents / Dependencies / CVE from Wave-1 may still be running; gather them before Step 5, not before Step 4.
 
-## Step 4: Dispatch Wave-3 — Predicate-Trace + Interaction Sweep + Gap-Finder
+### Step 4: Dispatch Wave-3 — Predicate-Trace + Interaction Sweep + Gap-Finder
 
 Once Wave-2 (Quality + Security) completes, dispatch 4a and 4b as parallel agents **in a single message**; compute 4c inline (orchestrator-side set arithmetic — no agent). They do NOT consume each other's output:
 
@@ -259,7 +257,7 @@ Once Wave-2 (Quality + Security) completes, dispatch 4a and 4b as parallel agent
 - **Gap-Finder (4c)** is coverage arithmetic: `{in-scope files} − {files with ≥1 Quality/Security finding} = {uncovered files}`. Orchestrator already holds both sets post-Wave-2 — an agent would discard context only to re-receive it via prompt. Inline is strictly cheaper and deterministic.
 - If Predicate-Trace (4a) surfaces a row that was not visible in Quality's table, append it via a Step 9 follow-up — cheaper than a serial gate.
 
-### Step 4a: Predicate-Trace
+#### Step 4a: Predicate-Trace
 
 **Gate**: SKIP this sub-step (do not dispatch 4a) unless `HasGatingPredicate` is true AND the Quality lens returned ≥2 rows in its `Predicate-set coherence` table referencing the same enum/type. If skipped, 4b and 4c still dispatch.
 
@@ -279,7 +277,7 @@ Otherwise spawn ONE `codebase-analyzer` in parallel with 4b:
 
 Do NOT wait — 4b (Interaction Sweep) dispatches in the same message as 4a; 4c runs inline in the orchestrator.
 
-### Step 4b: Interaction Sweep
+#### Step 4b: Interaction Sweep
 
 **Gate**: SKIP this sub-step (do not dispatch 4b) when EITHER `len(ChangedFiles) < 2` OR the Quality lens returned fewer than 4 total observations across all files. Emergent interactions need surface area; tiny diffs cannot structurally produce them.
 
@@ -308,7 +306,7 @@ Otherwise spawn ONE `codebase-analyzer` in parallel with 4a:
   For findings involving ordering/races/concurrency across processes or handlers, name the ordering primitive that would prevent the race (distributed lock, exclusive-key wrapper, ordered partition, transaction, idempotency key, etc.) and explain why it does NOT apply here. Drop the finding if the primitive exists in the diff or nearby and your argument against it is speculative.
   ```
 
-### Step 4c: Gap-Finder (orchestrator-side coverage arithmetic)
+#### Step 4c: Gap-Finder (orchestrator-side coverage arithmetic)
 
 **Gate**: SKIP when `len(ChangedFiles) < 2`. Tiny diffs cannot structurally have coverage gaps.
 
@@ -324,7 +322,7 @@ No agent dispatch. Compute inline while 4a / 4b run:
 
 **Wait for ALL of 4a / 4b AND the Precedents agent from Wave-1 to complete** before proceeding to Step 5 (Reconciliation). Precedents is a **hard gate** — severity weighting in Step 5 reads its follow-up-within-30-days counts. Dependencies / CVE (when dispatched) also merge in here but are not individually hard-gated; wait for them too unless they clearly exceed the review SLA, in which case omit `## Dependencies` and note it in the artifact. 4c has no wait — it completes synchronously with the orchestrator.
 
-## Step 5: Reconcile Findings
+### Step 5: Reconcile Findings
 
 **Barrier**: Step 5 MUST NOT begin until the Precedents agent has returned. Severity weighting depends on historical follow-up counts; starting reconciliation without them produces mis-weighted severities that the verification pass (Step 6) cannot correct.
 
@@ -363,7 +361,7 @@ No agent dispatch. Compute inline while 4a / 4b run:
        • *{spec A accepts Y} + {spec B rejects Y} + {workflow depends on both}* = **contradictory-predicate deadlock**
      Also check `thoughts/shared/reviews/*.md` and Precedents: if a prior review names a cascade whose constituents appear in current findings, cite it and assert reproduction. Missed cascades are the biggest historical quality regression; prefer false positives here.
 
-## Step 6: Verify Findings
+### Step 6: Verify Findings
 
 Before writing the artifact, spawn ONE `claim-verifier` whose sole job is to ground every reconciled finding in the actual code at its cited `file:line`. This catches two classes of error the lenses cannot self-detect: (a) *confident assertions* the agent never opened a file to confirm, and (b) *rationalisations* ("intentional-by-design", "pre-existing", "not a real deadlock") that contradict what the code does. Lens agents reason from the patch; the verifier reasons from the file.
 
@@ -407,7 +405,7 @@ Before writing the artifact, spawn ONE `claim-verifier` whose sole job is to gro
 
 **Do not skip this step** — it is the only mechanism that stops confident-but-unread lens assertions from reaching the artifact.
 
-## Step 7: Write the Review Document
+### Step 7: Write the Review Document
 
 1. **Determine metadata**:
    - Filename: `thoughts/shared/reviews/YYYY-MM-DD_HH-MM-SS_{scope-kebab}.md`
@@ -437,7 +435,7 @@ Before writing the artifact, spawn ONE `claim-verifier` whose sole job is to gro
 
 **Template shape**: Read the full template at `templates/review.md` (house pattern per `.rpiv/guidance/skills/architecture.md:66` — `templates/` subfolder, runtime-read, never inlined). At emission time: Read `templates/review.md`, fill every `{placeholder}` with reconciled-and-verified values from Steps 5 and 6, apply the section-omission rules above (delete the whole section AND its trailing separator line when its input is empty), strip the leading `<!-- -->` comment, and Write the result to the target path.
 
-## Step 8: Present Summary
+### Step 8: Present Summary
 
 ```
 Review written to:
@@ -465,7 +463,7 @@ Ask follow-ups, or chain forward.
 > 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.
 ```
 
-## Step 9: Handle Follow-ups
+### Step 9: Handle Follow-ups
 
 - **Append, never rewrite.** Edit the artifact to add a `## Follow-up {ISO 8601 timestamp}` section. The section heading's timestamp is the append-time record — no frontmatter update needed.
 - **Re-dispatch narrowly.** Spawn a single targeted `codebase-analyzer` on the area in question (1 agent max).

package/skills/commit/SKILL.md

@@ -9,9 +9,9 @@ allowed-tools: Bash(git *), Read, Glob, Grep
 
 You are tasked with creating git commits for repository changes.
 
-## Commit hint
+## Input
 
-`$ARGUMENTS` (empty/literal → infer from history and `git diff`)
+`$ARGUMENTS` — optional commit message hint. Empty/literal → infer from history and `git diff`.
 
 ## Context:
 - **In-session**: If there's conversation history, use it to understand what was built/changed

package/skills/create-handoff/SKILL.md

@@ -10,6 +10,9 @@ disable-model-invocation: true
 
 You are tasked with writing a handoff document to hand off your work to another agent in a new session. You will create a handoff document that is thorough, but also **concise**. The goal is to compact and summarize your context without losing any of the key details of what you're working on.
 
+## Input
+
+`$ARGUMENTS` — optional description (used in the handoff filename slug).
 
 ## Process
 ### 1. Filepath & Metadata

package/skills/design/SKILL.md

@@ -1,28 +1,26 @@
 ---
 name: design
 description: Design complex features by decomposing them into vertical slices and producing a design artifact (architecture decisions, slice breakdown, file map) in thoughts/shared/designs/. The design feeds the plan or blueprint skill. Use for complex multi-component features touching 6+ files across multiple layers, when the user wants a feature designed before implementation. Requires a research artifact or a solutions artifact (from explore). Prefer design over plan or blueprint when the focus is architecture and decomposition rather than phased execution steps.
-argument-hint: [research artifact path]
+argument-hint: "[research artifact path]"
 ---
 
 # Design
 
 You are tasked with designing how code will be shaped for a feature or change. This iterative variant decomposes features into vertical slices and generates code slice-by-slice with developer micro-checkpoints between slices. The design artifact feeds directly into plan, which sequences it into phases.
 
-**How it works**:
-- Read input and key source files into context (Step 1)
-- Spawn targeted research agents for depth analysis (Step 2)
-- Identify ambiguities — triage into simple decisions and genuine ambiguities (Step 3)
-- Holistic self-critique — review the combined design for gaps and contradictions (Step 4)
-- Developer checkpoint — resolve genuine ambiguities one at a time (Step 5)
-- Decompose into vertical slices holistically before generating code (Step 6)
-- Generate code slice-by-slice with developer micro-checkpoints (Step 7)
-- Verify cross-slice integration consistency (Step 8)
-- Finalize the design artifact (Step 9)
-- Review and iterate with the developer (Step 10)
+## Input
+
+`$ARGUMENTS` — path to a research artifact (`thoughts/shared/research/*.md`) or a solutions artifact (`thoughts/shared/solutions/*.md`).
+
+## Flow
+
+1. Input → 2. Research → 3. Dimension sweep → 4. Self-critique → 5. Checkpoint → 6. Decompose → 7. Generate slices → 8. Integration verify → 9. Finalize → 10. Review → 11. Follow-ups
 
 The final artifact is plan-compatible.
 
-## Step 1: Input Handling
+## Steps
+
+### Step 1: Input Handling
 
 When this command is invoked:
 
@@ -47,7 +45,7 @@ When this command is invoked:
 
 2. **Read any additional files mentioned** — tickets, related designs, existing implementations. Read them FULLY before proceeding.
 
-## Step 2: Targeted Research
+### Step 2: Targeted Research
 
 This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to follow) not BREADTH (where things are).
 
@@ -79,7 +77,7 @@ This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to
    - Note assumptions that need verification
    - Determine true scope based on codebase reality
 
-## Step 3: Identify Ambiguities — Dimension Sweep
+### Step 3: Identify Ambiguities — Dimension Sweep
 
 Walk Step 2 findings, inherited research Q/As, and carried Open Questions through six architectural dimensions that map 1:1 to `plan` extract sections — the sweep guarantees downstream completeness. Add **migration** as a seventh dimension only if the feature changes persisted schema.
 
@@ -94,7 +92,7 @@ For each dimension, classify findings as **simple decisions** (one valid option,
 
 **Pre-validate every option** before queuing it against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence. **Coverage check**: every Step 2 file read appears in at least one decision or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not).
 
-## Step 4: Holistic Self-Critique
+### Step 4: Holistic Self-Critique
 
 Before presenting ambiguities to the developer, review the combined design picture holistically. Step 3 triages findings individually — this step checks whether they fit together as a coherent whole.
 
@@ -114,7 +112,7 @@ Before presenting ambiguities to the developer, review the combined design pictu
 - Issues that need developer input: add as new genuine ambiguities to the Step 5 checkpoint queue.
 - If no issues found: proceed to Step 5 with the existing ambiguity set.
 
-## Step 5: Developer Checkpoint
+### Step 5: Developer Checkpoint
 
 Use the grounded-questions-one-at-a-time pattern. Use a **❓ Question:** prefix so the developer knows their input is needed. Each question must:
 - Reference real findings with `file:line` evidence
@@ -174,7 +172,7 @@ Files: {N} new, {M} modified
 
 Use the `ask_user_question` tool to confirm before proceeding. Question: "{Summary from design brief above}. Ready to proceed to decomposition?". Header: "Design". Options: "Proceed (Recommended)" (Decompose into vertical slices, then generate code slice-by-slice); "Adjust decisions" (Revisit one or more architectural decisions above); "Change scope" (Add or remove items from the building/not-building lists).
 
-## Step 6: Feature Decomposition
+### Step 6: Feature Decomposition
 
 After the design summary is confirmed, decompose the feature into vertical slices. Each slice is a self-contained unit: types + implementation + wiring for one concern.
 
@@ -238,13 +236,13 @@ After the design summary is confirmed, decompose the feature into vertical slice
    - **NEW files**: heading + empty code fence (filled with full implementation in Step 7d)
    - **MODIFY files**: heading with `file:line-range` + empty code fence (filled with only the modified code in Step 7d — no "Current" block, the original is on disk)
 
-## Step 7: Generate Slices (Iterative)
+### Step 7: Generate Slices (Iterative)
 
 Generate code one slice at a time. Each slice sees the fixed code from all previous slices.
 
 **For each slice in the decomposition (sequential order):**
 
-### 7a. Generate slice code (internal)
+#### 7a. Generate slice code (internal)
 
 Generate complete, copy-pasteable code for every file in this slice — but **hold it for the artifact, do NOT present full code to the developer**. The developer sees a condensed review in 7c; the full code goes into the artifact in 7d.
 
@@ -259,7 +257,7 @@ No pseudocode, no TODOs, no placeholders — the code must be copy-pasteable by
 
 **Context grounding** (after slice 2): Before generating, re-read the artifact's Architecture section for files this slice touches. The artifact is the source of truth — generate code that extends what's already there, not what you remember from conversation.
 
-### 7b. Self-verify slice
+#### 7b. Self-verify slice
 
 Before presenting to the developer, cross-check this slice and produce a structured summary:
 
@@ -272,7 +270,7 @@ Self-verify Slice N:
 
 If violations found: fix in-place before presenting. Include the self-verify summary in the 7c checkpoint presentation.
 
-### 7c. Developer micro-checkpoint
+#### 7c. Developer micro-checkpoint
 
 Present a **condensed review** of the slice — NOT the full generated code. The developer reviews the design shape, not every line. For each file in the slice, show:
 
@@ -290,7 +288,7 @@ Use the `ask_user_question` tool to confirm. Question: "Slice {N/M}: {slice name
 **Checkpoint cadence**: Slices 1-2: always individual. Slices 3+: individual if (a) mid-generation agent spawn was needed, (b) MODIFY touches an undiscussed file, or (c) self-verify fixed a violation.
 Otherwise batch 2-3 slices (max 3).
 
-### 7d. Incorporate feedback
+#### 7d. Incorporate feedback
 
 **Approve**: Lock this slice's code and **Edit the artifact immediately**:
 1. For each file in this slice, Edit the skeleton artifact to replace the empty code fence under that file's Architecture heading with the full generated code from 7a
@@ -304,7 +302,7 @@ Otherwise batch 2-3 slices (max 3).
 **Rethink**: Developer spotted a design issue. If a previously approved slice is affected, flag the conflict and offer cascade revision — developer decides whether to reopen (if yes, Edit artifact entry).
 Update decomposition (add/remove/reorder remaining slices) and confirm before continuing.
 
-## Step 8: Integration Verification
+### Step 8: Integration Verification
 
 After all slices are complete, review cross-slice consistency:
 
@@ -321,7 +319,7 @@ After all slices are complete, review cross-slice consistency:
 
 3. **Confirm using the `ask_user_question` tool**. Question: "{N} slices complete, {M} files total. Cross-slice consistency verified. Proceed to design artifact?". Header: "Verify". Options: "Proceed (Recommended)" (Finalize the design artifact (verify completeness, update status)); "Revisit slice" (Reopen a specific slice for revision — Edit the artifact after); "Add missing" (A file or integration point is missing — add to artifact).
 
-## Step 9: Finalize Design Artifact
+### Step 9: Finalize Design Artifact
 
 The artifact was created as a skeleton in Step 6 and filled progressively in Step 7d. This step verifies completeness and finalizes.
 
@@ -337,7 +335,7 @@ The artifact was created as a skeleton in Step 6 and filled progressively in Ste
    - **NEW files**: `### path/to/file.ext — NEW` + one-line purpose + full implementation code block
    - **MODIFY files**: `### path/to/file.ext:line-range — MODIFY` + code block with only the modified/added code (no "Current" block — the original is on disk, implement reads it)
 
-## Step 10: Review & Iterate
+### Step 10: Review & Iterate
 
 1. **Present the design artifact location**:
    ```
@@ -361,7 +359,7 @@ The artifact was created as a skeleton in Step 6 and filled progressively in Ste
    > 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.
    ```
 
-## Step 11: Handle Follow-ups
+### Step 11: Handle Follow-ups
 
 - **Edit in-place.** Use the Edit tool to update the design artifact directly — sliced design code stays one source of truth.
 - **Bump frontmatter.** Update `last_updated` + `last_updated_by`; set `last_updated_note: "Updated <brief description>"`.