@webpresso/plugin-opencode 0.0.6 → 0.0.7

package/skills/plan-refine/references/full-methodology.md

@@ -15,15 +15,27 @@
 
 ## Core Principle
 
-> **"A plan is only as strong as its weakest unchecked assumption — and only as fast as its coarsest task granularity."**
+> **"A plan is only as strong as its weakest unchecked claim — only as elegant as what it refuses to add — and only as fast as its coarsest task granularity."**
 
-Every technology claim, file path, API assumption, and architecture decision in a blueprint must be verified against reality before implementation begins. Unverified plans create cascading failures during execution. Poorly structured plans serialize work that could run in parallel — wasting 10x the wall-clock time.
+Every technology claim, file path, API, version, and architecture decision must be verified against reality before implementation. **Zero assumptions:** model memory is not evidence. Unverified plans cascade into execution failure. Coarse tasks serialize work that should run in parallel.
 
-Refinement has two equally important goals:
+### Non-negotiable bar (always)
 
-1. **Correctness** — Every claim is fact-checked, every edge case documented
-2. **Parallelizability** — Tasks are structured in Blueprint format with maximum independence for parallel execution (`/goal` autopilot, `ultragoal`)
-3. **Simplicity and safety** — DRY, SOLID, YAGNI, KISS, and public package leak-prevention gates are applied before abstractions or release surfaces are approved
+| Target              | Definition                                                                                | Fail condition                                                 |
+| ------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **100% confidence** | Every material claim has a code pinpoint and/or official-doc citation at a stated version | Any “probably / should work / AI recall” left standing         |
+| **Elegance**        | Smallest coherent design; delete/reuse over add                                           | Heavier option kept without recorded rejection of lighter ones |
+| **Durability**      | Survives upgrades and adjacent change; ownership boundaries clear                         | Rewrite-prone seams or version-blind third-party usage         |
+| **Efficiency**      | Minimal critical path; true parallel waves; no speculative work                           | False dependencies, CP > 0, busywork tasks                     |
+
+Refinement goals (all required):
+
+1. **Correctness** — Every claim fact-checked; every edge case documented
+2. **Zero assumptions** — Unproven statements removed or proven
+3. **Code pinpoints** — Paths, symbols, and signatures anchored in the repo
+4. **Official latest docs** — Third-party behavior from primary sources at latest/pinned version
+5. **Parallelizability** — Maximum independent tasks for `/goal` / `ultragoal`
+6. **Elegance, durability, efficiency** — Not merely correct; DRY/SOLID/YAGNI/KISS + public-package safety
 
 ## When to Use
 
@@ -45,65 +57,37 @@ Refinement has two equally important goals:
 
 ## The Refinement Pipeline
 
+Phases 1–3 (and independent review lenses) run **in parallel**. Only cross-plan alignment, blueprint enforcement, and apply need their inputs.
+
 ```
 Blueprint (Draft/In-Progress)
         │
-        ▼
-┌─────────────────────────────────┐
-│  PHASE 1: Technology Fact-Check │  ← Web research + docs
-│  - Library compatibility        │
-│  - API correctness              │
-│  - Version constraints          │
-│  - Runtime compatibility        │
-└──────────────┬──────────────────┘
-               │
-               ▼
-┌─────────────────────────────────┐
-│  PHASE 2: Codebase Verification │  ← Grep/Read existing code
-│  - File paths exist             │
-│  - APIs match signatures        │
-│  - Patterns match conventions   │
-│  - Dependencies available       │
-└──────────────┬──────────────────┘
-               │
-               ▼
-┌─────────────────────────────────┐
-│  PHASE 3: Architecture Review   │  ← Adversarial critique
-│  - Race conditions              │
-│  - Echo loops                   │
-│  - Error cascades               │
-│  - Concurrent access            │
-│  - Auth/session edge cases      │
-└──────────────┬──────────────────┘
-               │
-               ▼
+        ├──────────────────┬──────────────────┐
+        ▼                  ▼                  ▼
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+│ PHASE 1 (//)    │ │ PHASE 2 (//)    │ │ PHASE 3 (//)    │
+│ Official latest │ │ Code pinpoints  │ │ Architecture +  │
+│ 3rd-party docs  │ │ path + symbol   │ │ elegance/       │
+│ version-pinned  │ │ 0 assumptions   │ │ durability      │
+└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
+         └──────────────────┬──────────────────┘
+                            ▼
 ┌─────────────────────────────────┐
-│  PHASE 4: Cross-Plan Alignment  │  ← Read dependent blueprints
-│  - Upstream deps still valid    │
-│  - Downstream plans updated     │
-│  - No contradictions            │
+│  PHASE 4: Cross-Plan Alignment  │
+│  - Upstream/downstream contracts│
 │  - Shared decisions consistent  │
 └──────────────┬──────────────────┘
-               │
                ▼
 ┌─────────────────────────────────┐
-│  PHASE 5: Blueprint Enforcement  │  ← Structure for parallelism
-│  - Task granularity audit       │
-│  - Dependency graph validation  │
-│  - File conflict detection      │
-│  - Wave optimization            │
-│  - TDD steps in every task      │
+│  PHASE 5: Max-parallel Blueprint│
+│  - Split/merge for RW/CPR/CP=0  │
+│  - Depends + Files + TDD        │
 └──────────────┬──────────────────┘
-               │
                ▼
 ┌─────────────────────────────────┐
-│  PHASE 6: Apply & Consolidate   │  ← Edit blueprint
-│  - Apply all fixes (Fx tags)    │
-│  - Update Edge Cases table      │
-│  - Update Risks table           │
-│  - Update Technology Choices    │
-│  - Update cross-plan references │
-│  - Rewrite tasks in Blueprint fmt│
+│  PHASE 6: Apply & Consolidate   │
+│  - Fx tags, tables, waves       │
+│  - Ready only at 100% confidence│
 └─────────────────────────────────┘
 ```
 
@@ -134,20 +118,29 @@ surface before execution.
 
 ---
 
-## Phase 1: Technology Fact-Check
+## Phase 1: Technology Fact-Check (official, latest, version-pinned)
+
+**Goal:** Verify every external technology claim against **official/upstream primary sources** at the **latest stable or plan-pinned version**. Secondary sources (blogs, forums, model memory) never stand alone.
+
+### Source order (strict)
+
+1. Vendor/official docs for that version (docs site, OpenAPI, man pages)
+2. Upstream release notes / changelog for that version
+3. Package registry metadata (resolved version, peer deps, engines)
+4. Maintainer GH issues/discussions **only** as supplemental after (1–3)
 
-**Goal:** Verify every technology claim against official documentation and known issues.
+Route through `best-practice-research` when reusable; escalate to `deep-research` for multi-source depth. Prefer Context7/WebFetch of the **official** URL over search snippets.
 
 ### What to Check
 
-| Category                       | Check                                       | How                                                   |
-| ------------------------------ | ------------------------------------------- | ----------------------------------------------------- |
-| **Library compatibility**      | Does library X work with runtime Y?         | Web search `"library-name" + "runtime-name" + issues` |
-| **API correctness**            | Does the API exist as described?            | Read official docs via Context7 or WebFetch           |
-| **Version constraints**        | Is the version available? Breaking changes? | npm registry, changelogs                              |
-| **Native addon compatibility** | Does it compile for all targets?            | Check Bun/Node/Deno compatibility                     |
-| **Protocol correctness**       | Is the wire protocol right?                 | Official docs (e.g., WebSocket subprotocols)          |
-| **Platform limits**            | Are there timeout/memory/size limits?       | Platform docs (e.g., Workers limits)                  |
+| Category                       | Check                                        | How                                                        |
+| ------------------------------ | -------------------------------------------- | ---------------------------------------------------------- |
+| **Library compatibility**      | Does library X work with runtime Y at ver Z? | Official compat matrix + engines field + release notes     |
+| **API correctness**            | Does the API exist as described at that ver? | Official docs page for **that version**, not “latest blog” |
+| **Version constraints**        | Pinned/latest available? Breaking changes?   | Registry + changelog between plan version and current      |
+| **Native addon compatibility** | Compiles for all targets?                    | Official platform support + CI matrix docs                 |
+| **Protocol correctness**       | Wire protocol right?                         | Official protocol/spec docs                                |
+| **Platform limits**            | Timeout/memory/size limits?                  | Platform official limits docs (e.g. Workers)               |
 
 ### Output Format
 
@@ -156,34 +149,44 @@ For each finding, assign:
 - **ID**: F1, F2, F3...
 - **Severity**: CRITICAL (blocks implementation), HIGH (causes bugs), MEDIUM (suboptimal), LOW (cosmetic)
 - **Claim**: What the blueprint says
-- **Reality**: What documentation/research shows
+- **Reality**: What official docs show (quote or paraphrase + **URL + version/date**)
 - **Fix**: Concrete change to the blueprint
 
 ### Anti-Patterns
 
-| Anti-Pattern                          | Why It's Wrong                    | Do This Instead                           |
-| ------------------------------------- | --------------------------------- | ----------------------------------------- |
-| "Library X should work"               | Untested assumption               | Verify with official docs + GitHub issues |
-| Trusting AI knowledge of library APIs | Models hallucinate API signatures | Read actual docs via Context7/WebFetch    |
-| Assuming latest version compatibility | Breaking changes happen           | Check specific version compatibility      |
-| Ignoring native addon constraints     | Build failures in CI/CD           | Test against all target runtimes          |
+| Anti-Pattern                          | Why It's Wrong                    | Do This Instead                                   |
+| ------------------------------------- | --------------------------------- | ------------------------------------------------- |
+| "Library X should work"               | Untested assumption               | Official docs + version-pinned evidence           |
+| Trusting AI knowledge of library APIs | Models hallucinate API signatures | Fetch official docs for the exact version         |
+| "Latest" without stating which latest | Drift between refine and execute  | Record version identity (semver / date / channel) |
+| Blog/SO as sole source                | Often wrong or version-skewed     | Primary docs first; blogs only as supplemental    |
+| Ignoring native addon constraints     | Build failures in CI/CD           | Official target matrix + engines                  |
 
-## Phase 2: Codebase Verification
+## Phase 2: Codebase Verification (pinpoint to code)
 
-**Goal:** Verify every file path, import, API reference, and pattern assumption against the actual codebase.
+**Goal:** Prove every local claim against the live tree with **exact anchors** — path + symbol (+ line range when it reduces ambiguity). No “roughly around” or “probably in utils”.
 
-Use the lightest reliable inspection tool first: prefer `rg -n` for search, `sed -n` for exact line ranges, and only escalate to ad hoc scripts when the extraction genuinely needs structure across many files.
+Use the lightest reliable inspection tool first: prefer `rg -n` for search, read exact ranges for definitions, and only escalate to ad hoc scripts when structure across many files is required.
 
 ### What to Check
 
-| Category               | Check                                      | How                                     |
-| ---------------------- | ------------------------------------------ | --------------------------------------- |
-| **File paths**         | Do referenced files exist at stated paths? | `Glob` for patterns, `Read` for content |
-| **API signatures**     | Do functions have the expected parameters? | `Grep` for function definitions         |
-| **Import paths**       | Are package exports available?             | Read `package.json` exports field       |
-| **Existing patterns**  | Does the codebase use the assumed pattern? | `Grep` for similar code                 |
-| **Naming conventions** | Do new files follow existing naming?       | `ls` existing directories               |
-| **Configuration**      | Are config values/env vars available?      | Read config files, `.env.example`       |
+| Category               | Check                                      | How — evidence shape                         |
+| ---------------------- | ------------------------------------------ | -------------------------------------------- |
+| **File paths**         | Do referenced files exist at stated paths? | Path exists; cite path in the fix            |
+| **API signatures**     | Parameters/returns match the plan?         | `path` + symbol + signature snippet          |
+| **Import paths**       | Package exports available?                 | `package.json` `exports` field + importer    |
+| **Existing patterns**  | Assumed pattern actually used?             | 1–3 real call sites (path + symbol)          |
+| **Naming conventions** | New files match neighbors?                 | Sibling directory listing + one exemplar     |
+| **Configuration**      | Config/env keys real?                      | Config file / `.env.example` path + key name |
+
+### Evidence rule
+
+Every material correction must include a **code pinpoint** of the form:
+
+- `packages/foo/src/bar.ts` — `export function baz(...)` (or equivalent symbol)
+- or `packages/foo/package.json` — `exports["./bar"]`
+
+If you cannot produce a pinpoint, the claim is an **assumption** → drop it or block.
 
 ### Codebase Red Flags
 
@@ -192,10 +195,11 @@ Use the lightest reliable inspection tool first: prefer `rg -n` for search, `sed
 - Blueprint extends a class that doesn't exist yet (timing dependency)
 - Blueprint assumes a function returns X but it actually returns Y
 - Blueprint references env var that isn't in any config
+- Blueprint cites a helper without a path/symbol (un-pinpointed)
 
 ## Phase 3: Architecture Review
 
-**Goal:** Adversarial critique of the architecture — find every way it can break.
+**Goal:** Adversarial critique of the architecture — find every way it can break — then select the most **elegant, durable, and efficient** design the constraints allow (not merely a correct one). Record why lighter alternatives were rejected when a heavier option is kept.
 
 ### The Adversarial Checklist
 
@@ -609,18 +613,23 @@ Stop and escalate to the user if:
 - The number of CRITICAL + HIGH findings exceeds 10 (plan may need fundamental rethinking)
 - A technology assumption affects more than 3 tasks (cascading rewrite needed)
 - Parallelization score is **D** (1 task in Wave 0) — plan needs fundamental restructure
+- Any material claim still lacks a **code pinpoint** or **official-doc + version** after a full pass (confidence ≠ 100%)
+- The “ready” design is only correct, not the most **elegant / durable / efficient** option under constraints
 
 ## Parallel Agent Strategy
 
-The refinement pipeline itself is designed for parallel execution:
+The refinement pipeline itself **must** maximize concurrency:
+
+| Lane | Phase                    | Tools                                   | Focus                                                   |
+| ---- | ------------------------ | --------------------------------------- | ------------------------------------------------------- |
+| A    | Technology fact-check    | WebSearch, WebFetch, Context7, registry | Official latest docs, version-pinned APIs               |
+| B    | Codebase verification    | Grep, Glob, Read                        | Path + symbol pinpoints, 0 assumptions                  |
+| C    | Architecture review      | Blueprint + evidence from A/B           | Races, elegance, durability, efficiency                 |
+| D    | Review lenses (optional) | plan-*-review skills                    | CEO / design / eng / DevEx in parallel when independent |
 
-| Agent   | Phase                 | Tools                         | Focus                              |
-| ------- | --------------------- | ----------------------------- | ---------------------------------- |
-| Agent 1 | Technology Fact-Check | WebSearch, WebFetch, Context7 | Library docs, compatibility, APIs  |
-| Agent 2 | Codebase Verification | Grep, Glob, Read              | File paths, existing code patterns |
-| Agent 3 | Architecture Review   | Read (blueprint only)         | Adversarial critique, edge cases   |
+**Lanes A–C(/D) run in parallel.** Phases 4–6 (cross-plan, blueprint enforcement, apply) run after their inputs land — not after an artificial full serial wait when a subset already unblocks the next edit.
 
-Agents 1-3 run in parallel. Phases 4-6 (Cross-Plan, Blueprint Enforcement, Apply) run sequentially after all agents complete.
+**Do not** refine serially “for simplicity” when claims partition cleanly (external vs local vs architecture).
 
 ## Related Skills
 

package/skills/ralplan/SKILL.md

@@ -5,46 +5,173 @@ title: Ralplan Consensus Planning
 status: active
 scope: repo
 applies_to: [agents]
-related: [plan-refine, plan-eng-review, plan-ceo-review, plan-design-review, plan-devex-review]
+related:
+  [
+    deep-interview,
+    best-practice-research,
+    deep-research,
+    plan-refine,
+    plan-eng-review,
+    plan-ceo-review,
+    plan-design-review,
+    plan-devex-review,
+    ultragoal,
+    autopilot,
+    team,
+  ]
 created: "2026-07-13"
-last_reviewed: "2026-07-13"
+last_reviewed: "2026-08-03"
 name: ralplan
-description: "Consensus planning gate for plan-refine"
+description: "Grounded consensus plan gate: code, research, blueprint, plan-*, refine. No impl."
 ---
 
 # Ralplan Consensus Planning
 
+## Use when (freeform)
+
+- "ralplan", "consensus plan", "plan gate", "approve the plan first"
+- "research then plan", "ground the plan before coding"
+- user wants a durable blueprint ready for execution without implementing yet
+
 Use when the user invokes `$ralplan`, asks for RALPLAN, or wants consensus planning before execution.
 
-`ralplan` is an agent-kit planning gate, not an implementation lane. It applies consensus review to a durable plan before execution starts.
-
-## Workflow
-
-1. Create or identify the durable blueprint or plan artifact that will own the work.
-2. Run the `plan-refine` methodology against that artifact: verify local code facts, verify external claims when relevant, sharpen acceptance criteria, split independent work, and lock verification gates.
-3. Apply the relevant review lenses before execution:
-   - `plan-eng-review` for architecture, sequencing, tests, and rollout risk.
-   - `plan-ceo-review` when scope, customer value, or sequencing tradeoffs matter.
-   - `plan-design-review` when UI/UX is material.
-   - `plan-devex-review` when docs, CLI/API ergonomics, onboarding, or migration risk is material.
-4. Consolidate the reviews into one decision record with:
-   - decision and drivers
-   - alternatives considered
-   - material corrections
-   - implementation tasks and dependencies
-   - verification gates
-   - residual risks or blockers — record each as a closed decision row (Material Decisions) or a tech-debt record with an owner and follow-up; the Trust Dossier's Residual Unknowns section must still read exactly `None.` at promotion
-5. Stop at an approved plan or an explicit blocker. Do not edit implementation code from this skill unless the user explicitly changes the task from planning to execution.
+`ralplan` is an **orchestrated planning gate**, not an implementation lane. It produces one durable **blueprint**, reviews it, hardens it with `/plan-refine`, then stops.
+
+## Iron laws
+
+1. **Blueprint is the plan.** Freeform notes are not durable consensus. Create or bind a blueprint before reviews.
+2. **Ground before drafting.** Code dive (+ bounded external research when needed) happens **before** the blueprint draft is treated as serious.
+3. **Reviews before refine.** Run risk-matched `plan-*` skills on the blueprint, apply findings, **then** `/plan-refine`.
+4. **No implementation.** Do not edit product source, commit implementation, or start `ultragoal`/`team`/`autopilot` unless the user explicitly switches out of planning.
+5. **No review stampede.** Do not fan out multi-host outside-voice swarms. Prefer in-host skill loads; at most one outside voice only if the user asks or the change is auth / data-loss / public-API sensitive.
+6. **Efficiency by scope.** Skip optional phases that cannot change the plan (see Complexity tiers).
+
+## Complexity tiers (pick one early)
+
+| Tier     | Signals                                                       | Required path                                                                                                      |
+| -------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **XS**   | Single file/symbol, clear bugfix, no new deps/API             | Code dive → blueprint → `plan-refine` (add `plan-eng-review` only when architecture/tests/rollout are non-obvious) |
+| **S/M**  | Multi-file feature, local patterns known, maybe one known lib | Full path; best-practice-research (BPR) only if third-party/API correctness matters                                |
+| **L/XL** | New subsystem, auth/data/migration/public API, multi-package  | Full path + CEO (+ design/devex when material); prefer deliberate depth on risks                                   |
+
+If ambiguity is high (no clear goal, conflicting constraints), run `deep-interview` first, then resume ralplan.
+
+## Workflow (strict order)
+
+### 0. Intake
+
+- Capture problem, constraints, non-goals, and success signal from the user message and available context.
+- State the chosen complexity tier and which optional phases will run or skip (one short line).
+- If an existing blueprint already owns this work, bind it; do not create a duplicate.
+
+### 1. Code dive (always)
+
+- Inspect the live tree for owners, call sites, patterns, configs, and constraints.
+- Pin **our** dependency versions from `package.json` / lockfile / workspace manifests for anything the plan may touch.
+- Record code pinpoints (`path` + symbol) for every local claim that will enter the plan.
+- Prefer repo search/read tools; do not ask the user for facts the tree already answers.
+
+### 2. External research (conditional, bounded)
+
+Run when third-party behavior, SOTA practice, migrations, or framework APIs affect correctness. Skip when the answer is fully repo-local.
+
+- **Invoke** skill `best-practice-research` (BPR).
+- Prefer **official/upstream docs for the exact versions we use** (or the plan-pinned version). Match doc version to our version — do not invent "latest" that is not ours.
+- Credible GitHub (maintainer samples, well-starred reference implementations) is **secondary**, never ahead of official docs.
+- Stop when the recommendation is grounded enough to draft. No rabbit holes, no multi-hour literature digests.
+- Escalate to `deep-research` only when BPR is insufficient for a material multi-source decision.
+- Adoption/upgrade/replacement choices: surface evidence; leave the decision in the blueprint ADR, do not silently expand scope.
+
+### 3. Create the plan as a blueprint (always)
+
+- Create or identify the durable blueprint that owns the work:
+
+  ```bash
+  wp blueprint new "<concise goal>" --complexity <XS|S|M|L|XL>
+  ```
+
+  Prefer MCP blueprint tools when available. Use `wp blueprint start <slug>` only when work will continue on a managed worktree branch.
+
+- Write an initial draft into that blueprint: goal, non-goals, approach options (≥2 when non-trivial, or explicit rejection of alternatives), tasks, acceptance criteria, verification, risks.
+- Include a compact decision summary: **principles** (3–5 when non-trivial), **drivers** (top 3), **options** with pros/cons.
+- This draft is expected to be imperfect — reviews and refine will harden it.
+
+### 4. Plan reviews (invoke skills; after draft exists)
+
+Load and run the skill bodies — do not "roleplay a one-line eng vibe" without the skill checklist. Prefer the host Skill tool; if unavailable, **Read** the skill file under the projected skills surface and execute its checklist in full (never monologue a one-line substitute).
+
+| Skill                | When                                                                                     |
+| -------------------- | ---------------------------------------------------------------------------------------- |
+| `plan-eng-review`    | **Always** for S/M and L/XL; for XS only when architecture/tests/rollout are non-obvious |
+| `plan-ceo-review`    | Scope, wedge, customer value, or sequencing bets are material (default on for L/XL)      |
+| `plan-design-review` | UI/UX, visual hierarchy, or interaction design is material                               |
+| `plan-devex-review`  | CLI/API/SDK, docs, onboarding, or migration ergonomics are material                      |
+
+Rules:
+
+- Apply findings **into the blueprint** after each review (or once after the set if independent).
+- Independent reviews may run in parallel **only when** they do not depend on each other's edits; if eng findings reshape scope, re-run only the affected optional reviews.
+- Optional high-risk challenge: one sequential outside-voice pass (`codex` / `claude` / `opencode-go`) **after** eng review if the user asks or the change is auth / data-loss / public-API sensitive. Never parallel multi-host review.
+
+### 5. `/plan-refine` last (always)
+
+After plan-* findings are merged into the blueprint (or after draft when XS skipped eng), run **`plan-refine` on that same blueprint**.
+
+- Purpose: 100% confidence pinpoints, official-doc claim re-check, elegance/durability/efficiency, max-parallel task graph, Trust Dossier / residual-unknowns discipline.
+- **Mechanical handoff:** invoke `plan-refine` with the explicit note  
+  `plan-* reviews complete for this pass; skip lens re-run unless scope changes`.  
+  If refine itself **materially changes scope**, re-run only the affected `plan-*` lens, then continue refine apply — do not restart the full ralplan loop.
+- Early code dive + BPR shaped the draft; refine **re-verifies** material claims (intentional second pin, not optional).
+- Still **no implementation code**.
+
+### 6. Consolidate and stop
+
+Emit one decision record on the blueprint:
+
+- decision and drivers
+- alternatives considered
+- material corrections from reviews + refine
+- implementation tasks and dependencies (execution-ready waves when non-trivial)
+- verification gates
+- residual risks as closed Material Decisions or tech-debt with owner — Trust Dossier Residual Unknowns must read exactly `None.` at promotion
+
+**Stop.** Do not implement. Recommend an execution lane only: usually `ultragoal` / `goal` for durable work, `team` when parallel lanes are justified, `autopilot` when the user wants the full autonomous pipeline **after** an approved plan.
+
+## Anti-patterns
+
+| Anti-pattern                                      | Do instead                                                |
+| ------------------------------------------------- | --------------------------------------------------------- |
+| Jumping to code after a chat "plan"               | Blueprint + reviews + refine first                        |
+| Research rabbit holes / unversioned "latest" docs | BPR, version-matched official sources, early stop         |
+| Treating plan-* as vibes without loading skills   | Invoke Skill tool or Read the skill file checklist        |
+| plan-refine before plan-* on S/M or L/XL work     | Reviews first, refine last (XS may skip eng when obvious) |
+| Re-running all plan-* inside refine by default    | Skip unless scope changed                                 |
+| Multi-host review stampede                        | Zero or one outside voice, sequential                     |
+| Implementing "just a small start" inside ralplan  | Stop; hand off execution lane                             |
 
 ## Output
 
-Return a concise consensus plan with:
+Return a concise consensus result:
 
-- verdict: ready / ready with edits / blocked
+- **verdict:** ready / ready with edits / blocked
+- **blueprint** slug/path
+- **phases run / skipped** (tier + rationale)
 - decision and rationale
-- accepted review findings
-- task breakdown
+- accepted review findings (eng + any optional)
+- refine summary (confidence, material corrections)
+- task breakdown pointer (in blueprint)
 - required verification
-- recommended execution lane, usually `goal` for durable sequential work or `autopilot` for the full autonomous pipeline
+- recommended execution lane (not started)
+
+## Relationship to sibling skills
+
+| Skill                              | Role relative to ralplan                                              |
+| ---------------------------------- | --------------------------------------------------------------------- |
+| `deep-interview`                   | Pre-gate when requirements are too ambiguous to plan                  |
+| `best-practice-research`           | Phase 2 external evidence wrapper                                     |
+| `deep-research`                    | Escalation when BPR is not enough for multi-source depth              |
+| `plan-*`                           | Phase 4 product/eng review skills (Webpresso-curated plan review set) |
+| `plan-refine`                      | Phase 5 final harden; detailed checklist SSOT for surgery             |
+| `ultragoal` / `team` / `autopilot` | Post-approval execution only                                          |
 
-Use `plan-refine` as the detailed checklist source of truth when deeper plan surgery is needed.
+`ralplan` is a Webpresso-owned consensus gate, not a multi-agent role-runtime product. Consensus here means: grounded evidence → durable blueprint → independent review skills → refine → stop.

package/skills/team/SKILL.md

@@ -5,7 +5,7 @@ title: Team
 status: active
 scope: repo
 applies_to: [agents]
-related: [autopilot, goal, plan-refine, verify]
+related: [autopilot, goal, plan-refine, verify, handoff]
 created: "2026-07-13"
 last_reviewed: "2026-07-21"
 name: team

package/skills/tech-debt/SKILL.md

@@ -9,11 +9,16 @@ related: []
 created: "2026-05-07"
 last_reviewed: "2026-05-07"
 name: tech-debt
-description: "Tech-debt lifecycle skill for wp tech-debt creation, review, schema validation, and audits."
+description: "Tech-debt lifecycle via wp tech-debt. Use for capture debt, overflow from fix_budget."
 ---
 
 # tech-debt
 
+## Use when (freeform)
+
+- "tech debt", "capture debt", "park for later"
+- opportunistic `fix` / harness findings that exceed `fix_budget`
+
 Manage the tech-debt lifecycle using `wp tech-debt` commands.
 
 ## Usage
@@ -63,7 +68,7 @@ accepted → needs-remediation → monitoring → resolved
 
 ## Categories
 
-`complexity`, `testing`, `mutation`, `duplication`, `dependency`, `security`, `documentation`
+`complexity`, `testing`, `mutation`, `duplication`, `dependency`, `security`, `documentation`, `tooling`
 
 ## Frontmatter schema (required fields)