@gobing-ai/spur 0.3.40 → 0.3.42

package/plugins/sp/skills/code-implementation/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: code-implementation
+description: "The implementation competency — turn a task's requirements, AC, and design into production code: task-driven scope, stack-pattern selection, root-cause debugging, a Solution change-map. Triggers: \"implement\", \"write code\", \"add feature\", \"fix the bug\", \"refactor\", \"code this task\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  interactions:
+    - technique
+  competency: implementation
+  openclaw:
+    emoji: "⚙️"
+---
+
+# code-implementation — the implementation competency
+
+Turn a task's requirements, acceptance criteria, and design into production code. This is the deep
+competency the spine (`sp:spur-dev`) dispatches to at its `implement` step — it owns
+*how to implement well*, not *when to implement* (the spine decides that). Every deterministic write
+to the corpus still goes through `spur task update` (the CLI-gated write contract in
+`sp:spur-dev`'s `cross-cutting.md`).
+
+## When to use
+
+- **New implementation** — write the code for a task whose requirements and design are settled.
+- **Bug fixes** — reproduce, isolate root cause, fix the cause not the symptom (see debugging).
+- **Refactors with test safety** — restructure behind passing tests.
+- **The pipeline's `implement` step** — `/sp:dev-run --mode implement <wbs>` dispatches here.
+
+Do **not** use this skill for:
+
+- **Coverage / gap analysis / test extension** — that is `sp:code-testing`.
+- **Test-first discipline (red-green-refactor)** — that is `sp:test-driven-development` (composed with this skill).
+- **System design / architecture decisions** — that is `sp:sys-architecture` (decide the shape first).
+- **Review / verification** — that is `sp:code-verification`.
+- **Driving the lifecycle** — that is the spine, `sp:spur-dev`.
+- **Re-launching the task pipeline from inside implement** — see anti-recursion below (bug-742).
+
+## Anti-recursion (pipeline implement step — bug-742)
+
+When this skill is entered via `/sp:dev-run --mode implement <wbs>` (the form
+`task-pipeline.yaml` `implement` uses as a **pure slash command** — ADR-043):
+
+1. Work **only** in the current working tree on that WBS. Implement code + author `## Solution`.
+2. **NEVER invoke** `spur workflow run` for `task-pipeline.yaml` (or any full task pipeline).
+3. **NEVER invoke** `/sp:dev-run` **without** an explicit `--mode implement`. Omitting the mode
+   defaults to full pipeline and **recurses** into another `implement` step (bug-742).
+4. Do **not** call `/sp:dev-runall`, `/sp:dev-verify`, or other lifecycle stages from inside this
+   skill — the pipeline (or `--next` chain) owns those hops.
+
+The structural guard is the slash form itself (`--mode implement`). Prose in the workflow YAML
+`agent.run` `input` is the wrong place for this rule; it belongs here and in `dev-run.md`.
+
+## One WBS per implement pass (task 0487 R1)
+
+The target WBS is the **only** task you implement. Sibling tasks in the corpus are context you do
+not have and work you were not asked to do.
+
+- **Read** the target task file, the tasks named in its `dependencies`, its `feature_id` feature
+  file, and the source files its Requirements / Design / Plan name. That is the whole input set.
+- **Ignore every other `todo` / `wip` task in the tree**, including ones whose files changed
+  recently. A task that looks half-finished is not an invitation — a freshly *committed* task can
+  legitimately still be `status: todo` because its verify/wrap hops have not run yet.
+- **Never implement a requirement belonging to another WBS**, even when it looks like a
+  prerequisite. If the target genuinely cannot proceed without it, stop and say so — a blocked task
+  is a cheap finding; a two-task diff costs the reverts.
+
+Why this is a rule and not a nicety: driving task 0486 lost several hours to exactly this. Task 0485
+was committed but still `todo` in the tree, and two different executors (omp run `ca130182`, claude
+run `b16bfbf4`) each pulled 0485's observability feature and its tests into 0486's diff, unprompted.
+A third agent reproduced it. The scope creep had to be detected and reverted four times.
+
+The pipeline enforces this on the way out: the implement step's `requireDiff` gate also checks diff
+*scope* against the files and explicit directory/glob prefixes the task body backticks, and routes
+the run to `failed` naming any file outside them (new files beside a declared file are allowed;
+bypass: run var `implementScopeGuard: "off"`). It compares snapshots taken immediately before and
+after dispatch, so dirt already in the tree is not attributed to this pass. Keeping the diff to one task's
+surfaces is what keeps that gate quiet.
+
+## Implement scope: do not run the project quality gate
+
+During implement, the pipeline's `test` hop runs `${vars.qualityGateCmd}` (the full project gate:
+`bun run format && bun run spur-check`) immediately after this step and is the gate that actually
+decides pass/fail. Running it inside implement is pure redundancy — it cannot change the outcome and
+only burns wall clock and context budget.
+
+- **Run only targeted probes** to validate your changes: `bun test <file>`,
+  `bun test <file> --test-name-pattern "<test>"`, or `bunx tsc --noEmit` on a single package.
+- **NEVER run** `bun run test`, `bun run spur-check`, `bun run check`, or any other full-suite /
+  project-gate command from inside implement. These belong to the pipeline's `test` hop.
+- If a targeted probe reveals a failure you cannot fix within implement scope, note it in
+  `## Solution` and let the `test` hop's fixall handle it — do not pre-empt the gate.
+
+## Behavior
+
+This skill behaves as a **technique**: given a task (read its Background, AC, Design, Plan), it maps
+requirements to files, picks the narrowest verification, implements in small slices fixing root
+causes, and writes a `## Solution` change-map via `spur task update`. It implements **only** behavior
+that traces to the task's AC or design — adjacent cleanup is recorded as a follow-up, not folded in.
+
+Full procedure: **[references/implementation-patterns.md](references/implementation-patterns.md)** —
+preconditions, task-driven scope, pattern selection, progress persistence, handoff to testing/review.
+
+## Composition with the discipline + test skills
+
+- **`sp:test-driven-development`** — when the work is test-first, this skill composes with the TDD discipline:
+  TDD designs the failing test, this skill writes the minimal code to pass it.
+- **`sp:code-testing`** — after implementation, coverage/gap work runs there. The per-stack adapters
+  (`stacks/<stack>.md`) that name build/test commands and idioms live in `code-testing` (operationally
+  loaded by its detect→load→run flow); reference them cross-skill when you need the stack's idioms.
+
+## Debugging
+
+When implementation hits a failing gate, a failing test, a runtime defect, or flaky behavior, switch
+to the root-cause-first workflow: **[references/debugging.md](references/debugging.md)** —
+reproduce → isolate → minimal fix → regression guard.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The spec is clear — I don't need to read the callers." | Code that looks orthogonal is how regressions ship (R5). Read the exports you touch and their immediate callers before writing. |
+| "I'll add the tests in a follow-up." | Untested production code is unverified code. The task's test step is not optional; behavior ships with its test. |
+| "This abstraction will be useful later." | Speculative abstraction is complexity without a caller (R2). Build for the requirement in front of you; add the seam when the second use arrives. |
+| "Close enough to the AC — the intent is there." | "Close enough" is a FAIL at verify. Implement to the literal AC; if the AC is wrong, fix the AC, don't approximate it. |
+| "I'll improve this adjacent code while I'm here." | Drive-by edits widen the diff and the blast radius (R3). Stay in scope; split unrelated cleanup into its own task. |
+| "Task 0485 is still `todo` and clearly unfinished — I'll finish it while I'm in here." | It is not your WBS. `todo` often just means the verify/wrap hops have not run yet. Implementing it costs the reverts and fails the scope guard (0487 R1). |
+| "It compiles and runs, so it's done." | Compiling is not the bar. Done is the AC met, tests green, and the `## Solution` change-map written. |
+
+## Red Flags
+
+- Writing code without having read the immediate callers of what you're changing.
+- A `## Solution` section that lists files but not what changed or why.
+- A `## Solution` section with file references that are not in backtick `` `path:line` `` form (L3 requirement: `` `packages/app/src/foo.ts:123` `` or `` `packages/app/src/bar.ts:10-20` ``; paths from repo root).
+- A new abstraction with exactly one caller and no second use in sight.
+- The diff touches files unrelated to the task's scope.
+- The diff touches another WBS's surfaces, or the pass reads sibling `todo` / `wip` task files.
+- "Done" claimed with no test run pasted.
+- Silently changing an AC's meaning to match what was built.
+- From implement mode: launching `spur workflow run …task-pipeline…` or `/sp:dev-run` without
+  `--mode implement` (recursive pipeline — bug-742).
+
+## Gotchas
+
+1. **The task is the scope.** Implement only what traces to AC/design; record adjacent cleanup as a
+   follow-up WBS rather than expanding the change.
+2. **Root cause, not symptom.** A green gate reached by suppressing a check is not done.
+3. **Never let a partial deliverable look complete.** Mark deferred requirements visibly in Solution
+   and Review with the follow-up WBS.
+4. **The spine owns the lifecycle.** This skill writes `## Solution`; status transitions and the
+   other sections are the spine's / other competencies' concern.
+5. **Implement is not the pipeline driver.** Pipeline YAML may only pass the pure slash
+   `/sp:dev-run --mode implement <wbs> …` (ADR-043). If anti-recursion text is missing from the
+   skill/command and you are tempted to paste it into YAML `input:`, put it here instead.
+
+## See also
+
+- **`sp:spur-dev`** — the spine that dispatches this competency at the `implement` step.
+- **`sp:code-testing`** — coverage and test extension; owns the per-stack adapters.
+- **`sp:test-driven-development`** — the test-first discipline this skill composes with.
+- **`sp:sys-architecture`** — decide the design/shape before implementing it.
+- **[Verification Before Completion](../spur-dev/references/cross-cutting.md#verification-before-completion)** — no "done / passing / fixed" claim without fresh, pasted evidence run this turn.
+
+## Platform Notes
+
+### Claude Code
+
+Invoked via `/sp:dev-run --mode implement <wbs>` (which the pipeline's `implement` step calls), or
+directly via `Skill(skill="sp:code-implementation", args="<wbs>")`. Deterministic writes use the
+`spur` CLI via the Bash tool.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Invoke this skill directly for implementation technique; run the `spur` CLI via the Bash tool for
+corpus writes. The skill is the SSOT; commands and the pipeline step are thin wrappers.

package/plugins/sp/skills/code-implementation/references/debugging.md

@@ -0,0 +1,64 @@
+---
+name: debugging
+description: "Root-cause-first debugging workflow for failed gates, failing tests, runtime defects, and flaky behavior during the sp execution loop."
+see_also:
+  - code-implementation
+  - code-testing
+  - code-verification
+---
+
+# Debugging
+
+Use this reference when the execution loop hits an unexplained failure: a test fails for an unclear
+reason, a runtime error appears, behavior is intermittent, or repeated fixes expose new failures.
+The rule is simple: **root cause before fix**. Do not patch the symptom just to move the pipeline.
+
+## When To Switch Into Debugging
+
+Switch from implementation or testing into debugging when any of these happen:
+
+- a test failure is not explained by the current requirement change
+- a command fails differently after a fix attempt
+- behavior is intermittent or timing-dependent
+- a regression appears after a recent change
+- two fix attempts fail to move the same gate
+- the observed symptom is far from the code that was changed
+
+If three fixes fail consecutively, stop implementation and reframe. That usually means the defect is
+in an assumption, seam, or test setup, not in the line being edited.
+
+## Four-Phase Workflow
+
+1. **Capture the symptom.** Preserve the exact command, error message, stack trace, input, and
+   environment. If you cannot reproduce it, you cannot verify the fix.
+2. **Trace to origin.** Start where the error appears, then follow the data and call chain backward:
+   what called this, what value was passed, where did that value originate?
+3. **Test one hypothesis.** State one cause, predict what evidence should change, then run the
+   smallest probe. Change one variable at a time.
+4. **Fix at the source.** Add or update a regression test first when practical, apply the smallest
+   source fix, then run the narrow test and the relevant wider gate.
+
+## Failure Taxonomy
+
+| Pattern | Signal | Debug Strategy |
+|---------|--------|----------------|
+| Null or undefined propagation | type/null error at a downstream call | Trace return values upward; validate at the boundary that introduced the value. |
+| Race or ordering bug | intermittent failure, timing sensitivity | Add deterministic synchronization; avoid sleeps as proof. |
+| State corruption | output is wrong after shared mutable state changes | Isolate mutation points; prefer immutable or copied state at seams. |
+| Type/shape mismatch | field access fails or logic takes the wrong branch | Resolve the actual type definition; add a parser/guard at input boundaries. |
+| Config drift | works locally but not in another environment | Centralize config loading; validate expected keys and paths at startup. |
+| Resource leak | degrades over time, hangs, or leaves handles open | Check acquisition/release pairs on every path. |
+| N+1 or repeated I/O | slow request or command with repeated calls | Batch, cache, or move lookup outside loops. |
+
+## Evidence Standard
+
+Every debugging handoff or solution note should include:
+
+- failing command or reproduction input
+- root cause, not just symptom
+- evidence that confirmed it
+- fix applied
+- verification command and result
+
+Do not claim "fixed" from a green narrow probe alone when the defect class could affect the wider
+gate. Run the smallest meaningful wider check before handing back to the pipeline.

package/plugins/sp/skills/code-implementation/references/implementation-patterns.md

@@ -0,0 +1,113 @@
+---
+name: implementation-patterns
+description: "Production implementation discipline for the sp execution loop: task-driven scope, branch/worktree hygiene, stack pattern selection, progress persistence, and handoff."
+see_also:
+  - code-implementation
+  - code-testing
+---
+
+# Implementation Patterns
+
+This reference is the core of the `code-implementation` competency skill — the discipline the
+spine's `implement` step dispatches to. It is not a separate command: deterministic writes still go
+through `spur task update`, and the spine (`sp:spur-dev`) owns the lifecycle that invokes this skill.
+
+## Preconditions
+
+Before writing code:
+
+1. Read the task's Background, Acceptance Criteria, Design, and Plan.
+2. Confirm the task is small enough to implement as one coherent change. If it is not, split or
+   create follow-up tasks before coding.
+3. Check the worktree and branch. Avoid mixing unrelated changes into the implementation evidence.
+4. Identify the stack and local conventions before adding files.
+5. Choose the narrowest verification command that proves the first behavior.
+6. **Reuse context from prior chain steps.** When this skill is invoked via a `--next` chain
+   (refine → run → verify), the calling session already holds the task file, `spur task check`
+   output, and any files read during refinement. Before re-reading a file, check whether it is
+   already in context — re-reading the task file or re-running `spur task check` when the prior
+   step's result is still valid wastes tokens and drags cache hit rate below 40%. Only re-fetch
+   when the underlying state changed (e.g. you just wrote a section and need the updated check).
+   Apply the same discipline to skill/command reference files: if the task's own references or
+   the refine step already loaded them, reference the in-context copy rather than re-reading.
+
+## Task-Driven Implementation
+
+The task is the source of scope. Implement only behavior that traces to the task's acceptance
+criteria or design. If you discover adjacent cleanup, record it as a follow-up unless it directly
+unblocks the requirement.
+
+**Scope the context to the target WBS (task 0487 R1).** The input set is the target task file, the
+tasks named in its `dependencies`, its `feature_id` feature file, and the source files its
+Requirements / Design / Plan name — nothing else. Other `todo` / `wip` tasks in the corpus are out
+of scope even when recently changed: a committed task can still read `todo` because its verify/wrap
+hops have not run. Implementing one alongside the target is the 0486 conflation (see
+`../SKILL.md` § One WBS per implement pass), and the pipeline's diff-scope guard fails the step for
+it.
+
+Use this sequence:
+
+1. **Map requirement to files.** Identify the module, seam, config, docs, or tests that must change.
+2. **Choose a test strategy.** Use `sp:test-driven-development` for test-first work, or `sp:code-testing` for
+   gap-filling coverage on existing code.
+3. **Implement in a small slice.** Keep the first slice narrow enough to verify.
+4. **Run the narrow check.** Fix root causes, not symptoms.
+5. **Update the task Solution.** The `implement` step owns `## Solution`; write a change map through
+   `spur task update <wbs> --section Solution --from-file <tmp>`.
+   Every file reference in the Solution MUST use backtick `` `path:line` `` form with paths from
+   repo root (e.g. `` `packages/app/src/foo.ts:123` `` or `` `packages/app/src/bar.ts:10-20` ``).
+   Prose `path:line` without backticks will fail `spur task check` (L3 stale-anchor detection).
+   `spur task record --solution-from-diff` is complementary — it backfills the change map from
+   git diff — but implement-time Solution is the authoritative source and must carry the
+   backtick format.
+
+## Pattern Selection
+
+Use existing local patterns first. Only introduce a new abstraction when it removes real complexity,
+matches an established seam, or gives a second concrete adapter/caller.
+
+| Domain | Default Pattern |
+|--------|-----------------|
+| API shape | Resource or operation names that match existing route/contract vocabulary; structured errors with context. |
+| Persistence | Existing DAO/service boundary; one lock/write domain for corpus changes. |
+| Config | Existing zod/config loader; no ad hoc environment reads in feature code. |
+| Process/file I/O | Existing runtime/process/file-system seam where the app already has one. |
+| Tests | Behavior names, boundary mocks only, fixtures/builders for noisy inputs. |
+| Documentation | Authoritative docs only; update `04_DESIGN.md` for command/config/schema changes. |
+
+## Progress Persistence
+
+Long implementation steps should leave resumable evidence:
+
+- code changes stay scoped to the task
+- Solution lists changed files and why
+- Testing records commands run and result
+- Review records open risks or deferred work
+
+If the task ships a partial deliverable, mark it visibly in Solution and Review with the deferred
+requirement and follow-up WBS. Do not let a partial implementation look complete.
+
+## Task-Type Awareness
+
+The implement step assumes a standard implementation task (`template: default`). When the task
+carries a different template, the implement agent MUST check the task's frontmatter `template`
+field and adjust its scope:
+
+| Template | Scope | Primary input |
+|----------|-------|---------------|
+| `default` | Implement `## Requirements` → code changes | `## Requirements` R-items, `## Design`, `## Plan` |
+| `review` | Fix the findings in `#### Review Findings` → code changes | `#### Review Findings` table (under `### Background`), `## Plan` |
+| `brainstorm` | Research/ideation → `## Solution` write-up | `## Background` prompt, `## Design` constraints |
+
+The implement agent reads the template field first, then picks the correct input section. For a
+`review` task, the `#### Review Findings` table IS the requirements — fix each finding in
+severity order (P1 → P2 → P3 → P4), then re-review.
+
+## Handoff To Testing And Review
+
+Implementation is complete only when:
+
+- the relevant narrow checks pass
+- the Solution section has a useful change map
+- no known requirement is silently deferred
+- the next gate can run without needing hidden context from the implementer

package/plugins/sp/skills/code-improvement/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: code-improvement
+description: "Surface architectural friction and propose deepening opportunities — refactors that turn shallow, tightly-coupled modules into deep, testable, AI-navigable ones. Triggers: \"improve architecture\", \"find refactoring opportunities\", \"shallow module\", \"hard to test\", \"reduce coupling\", \"deepen modules\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  interactions:
+    - reviewer
+    - pipeline
+  modes:
+    - review
+  openclaw:
+    emoji: "🏗️"
+see_also:
+  - sp:code-verification
+  - sp:functional-review
+  - sp:spur-dev
+---
+
+# Spur Code Improvement
+
+The **architecture and structural depth** counterweight to `sp:code-verification`'s SECUA review.
+Where code-verification asks "is the code correct/secure/efficient?", code-improvement asks "is the
+architecture deep, testable, and navigable — or is it a pile of shallow pass-through modules held
+together by tight coupling?"
+
+## When to Use
+
+**Trigger keywords:** improve architecture, refactor, shallow module, tightly coupled, untestable,
+AI-navigable, deepening, consolidate modules, reduce coupling, architectural friction, hard to
+test, pass-through module.
+
+Load this skill when:
+
+- Surfacing architectural friction and deepening opportunities as ranked candidates.
+- Running the architecture dimension of a multi-dimensional review (`/sp:dev-review --focus architecture`).
+- Auditing a module or package for structural debt before a refactor.
+- Producing an advisory (non-blocking) deepening report to accompany a SECUA review.
+
+Do **not** use this skill for:
+
+- Requirements traceability (use `sp:functional-review`).
+- SECUA quality review (use `sp:code-verification`).
+- Implementing the refactor (use `sp:code-implementation` — this skill *surfaces*, it does not ship).
+
+## Key Distinctions
+
+| Skill | Question it answers |
+|-------|---------------------|
+| **`sp:code-improvement`** | Is the architecture deep / testable / navigable? (structural depth) |
+| **`sp:functional-review`** | Are all task requirements implemented? (requirements completeness) |
+| **`sp:code-verification`** | Is the code correct, secure, efficient, usable? (SECUA quality) |
+
+A complete `/sp:dev-review --focus all` runs all three. This skill owns the **architecture**
+dimension; the others are out of scope here.
+
+## Cross-cutting rules (inherited from sp:spur-dev)
+
+CLI-gated section writes: see
+[spur-dev/cross-cutting.md](../spur-dev/references/cross-cutting.md). Universal honesty gate: see
+[Verification Before Completion](../spur-dev/references/cross-cutting.md#verification-before-completion).
+
+---
+
+## Improvement Lenses
+
+Five signals indicate a shallow or tightly-coupled module. Each defines a symptom, a diagnostic,
+and the deepening direction. Full definitions and examples in
+[references/deepening-signals.md](references/deepening-signals.md).
+
+| # | Signal | Symptom | Deepening direction |
+|---|--------|---------|--------------------|
+| 1 | **Shallow module** | A module whose interface is as complex as its implementation | Collapse it into its caller or give it a real body |
+| 2 | **Tight coupling** | Two modules that must change together | Introduce a seam (interface, event, or DTO) |
+| 3 | **Wrong seam** | Abstraction boundary in the wrong place | Move responsibility across the seam |
+| 4 | **Weak locality** | Related logic scattered across modules | Co-locate by responsibility |
+| 5 | **Poor test surface** | Logic that can only be tested through a large stack | Extract a pure function or inject a boundary |
+
+---
+
+## Severity
+
+| Severity | Blocking? | Description |
+|----------|-----------|-------------|
+| **blocker** | yes — must fix before merge | The architecture cannot support the current or next change without a structural fix. Examples: circular dependency, module with no test surface, a seam that leaks domain types across a boundary. |
+| **major** | yes (in pipeline context) | Significant friction: a shallow module duplicated 3+ ways, tight coupling that forces coordinated changes across packages, a wrong seam that blocks a planned feature. |
+| **minor** | advisory | Local friction: a module slightly too shallow, coupling that's awkward but not coordinated. |
+| **advisory** | advisory | Deepening opportunity: the code works and is testable, but would be cleaner with a deeper module. Always non-blocking. |
+
+**Under the pipeline** (`/sp:dev-review` in a task run), `blocker` and `major` block the
+`approve(HITL)` gate. `minor` and `advisory` are recorded but do not block. **Standalone** reviews
+are advisory-only — the operator decides what to act on.
+
+---
+
+## Workflow
+
+### Step 1 — Establish scope
+
+```bash
+spur task show <wbs> --json    # for a pipeline run
+# OR a path glob for standalone:
+# scope = 'src/api/' | 'packages/domain/' | 'plugins/sp/'
+```
+
+For a pipeline run, derive the diff scope the same way `sp:code-verification` Step 3 does (the
+task's last commit → changed `*.ts/*.tsx/*.js/*.jsx`). For standalone, the `path` argument is the
+scope.
+
+### Step 2 — Explore (read the map)
+
+Build a module-level map of the scope:
+
+- List the modules (files / directories) in scope.
+- For each, read its exports and immediate callers (use LSP `references` / `definition` where
+  available; fall back to `grep` + `read`).
+- Identify the module's **interface** (exported surface) and its **implementation** (non-exported
+  body). A module is shallow when the interface is as complex as the implementation.
+
+### Step 3 — Apply the five lenses
+
+For each module in scope, check each of the five improvement signals:
+
+1. **Shallow module?** Is the exported surface as complex as the body? (interface-to-impl ratio
+   ≈ 1:1)
+2. **Tight coupling?** Does this module change in lockstep with another? (grep for co-changed
+   symbols, shared mutable state, deep relative imports)
+3. **Wrong seam?** Is the abstraction boundary in the wrong place? (domain types leaking across a
+   transport seam, a service importing a DAO directly instead of through a repository, etc.)
+4. **Weak locality?** Is related logic scattered? (a single responsibility spread across N files)
+5. **Poor test surface?** Can the core logic be tested without standing up a large stack? (no pure
+   extraction, no injectable boundary)
+
+For each signal hit, record a **candidate** using the Candidate Format below.
+
+### Step 4 — Present candidates
+
+Emit the ranked candidate list. Do **not** implement — this skill surfaces, it does not ship. The
+operator (or `sp:code-implementation`) decides what to act on.
+
+### Step 5 — Grilling (optional, `--auto` skips)
+
+For each `blocker`/`major` candidate, state the single hardest *challenge* to the deepening
+proposal ("what breaks if we do this?") and the single hardest *defense*. If the defense cannot
+answer the challenge, downgrade the severity or drop the candidate. Three cycles max; stop sooner
+if satisfied.
+
+---
+
+## Candidate Format
+
+Each candidate is a structured finding:
+
+```markdown
+### C{n} — {signal name} in `{module}`
+
+- **Severity:** blocker | major | minor | advisory
+- **Signal:** shallow module | tight coupling | wrong seam | weak locality | poor test surface
+- **Location:** `path/to/module.ts:42`
+- **Symptom:** <1-2 sentences — what's wrong, concretely>
+- **Evidence:** <file:line anchors showing the signal>
+- **Deepening proposal:** <the structural change that would fix it>
+- **Challenge:** <the hardest objection to the proposal>
+- **Defense:** <the answer to the challenge, or "none — downgrade">
+- **Affected files:** <list of files the refactor would touch>
+```
+
+---
+
+## Context Inputs
+
+- **`CONTEXT.md`** (if present in the repo root or a package) — domain vocabulary. Use its terms
+  in symptom descriptions to keep candidates readable for the team.
+- **`docs/adr/`** (if present) — architectural decisions. A candidate that contradicts an ADR
+  must cite the ADR and propose superseding it (do not silently diverge — same rule as the docs
+  constitution).
+- **Neither present?** Proceed without them; the five signals are self-contained.
+
+---
+
+## Multi-dimensional review integration
+
+When invoked as the `--focus architecture` dimension of `/sp:dev-review`:
+
+- The scope is the task's diff (pipeline) or the `path` arg (standalone).
+- `blocker`/`major` candidates block the `approve(HITL)` gate alongside any SECUA blockers from
+  `sp:code-verification`.
+- The candidate list is recorded in the task's `## Review` section (written by the pipeline's
+  `record` step via `spur task update --section`).
+- This skill does **not** write to the task file directly — the pipeline (or the operator) does.
+
+Standalone, the skill emits the candidate list as advisory output; the operator acts on it.
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It works, so the architecture is fine." | Working code can still be shallow or tightly coupled. This skill judges *depth*, not correctness. |
+| "We can refactor that later." | "Later" is how structural debt compounds. A `blocker` says *now*; `advisory` says *later*. |
+| "It's just a small wrapper." | A small wrapper IS the shallow module. Collapse it or give it a real body. |
+| "The coupling is necessary for performance." | Cite the measurement. Unmeasured "necessity" is rationalization. |
+| "I don't see how to deepen this." | If the proposal has no defense after Grilling, drop the candidate — don't pad the report. |
+
+---
+
+## Gotchas
+
+1. **Surface, don't ship.** This skill produces candidates. Implementation is `sp:code-implementation`.
+2. **Advisory by default standalone.** Only under the pipeline do `blocker`/`major` block.
+3. **ADR awareness.** A candidate that contradicts an ADR proposes superseding it — never silently
+   diverge (mirrors the docs constitution's binding rule).
+4. **No file:line, no candidate.** Every candidate's `Evidence` field must cite specific anchors.
+5. **Grilling is a filter, not a ritual.** Three cycles max; if the defense fails, drop or downgrade.
+
+---
+
+## Platform Notes
+
+### Claude Code
+
+Invoke via `Skill(skill="sp:code-improvement", args="<path|wbs>")`. LSP `references` /
+`definition` are available for the Explore step.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Run `spur` CLI via Bash; `grep` + `read` for the Explore step if no LSP. The skill is the SSOT;
+execute the workflow steps inline.