replan

Files (5)

• SKILL.md
• owns-defers.md
• boundary-with-goals.md · references/
• clarifying-amendments.md · references/
• worked-examples.md · references/

SKILL.md (first lines)

# Replan (QRSPI — out-of-route)

**PRECONDITION:** Invoke `qrspi:using-qrspi` skill to ensure global pipeline rules are in context. (Idempotent on session re-entry. Subagents are exempt — SUBAGENT-STOP in using-qrspi handles that.)

**Announce at start:** "I'm using the QRSPI Replan skill to update remaining tasks based on phase learnings."

## Overview

Subagent analyzes completed phase, proposes updates with severity classification. Runs between phases only — not at end of final phase.

## Replan OWNS / Replan DEFERS

This section is the **single source of truth** for Replan scope boundaries. Phase-transition execution (the minor-path archive-and-populate sequence) is owned here; all phasing decisions and roadmap authoring are deferred to Phasing.

### Replan OWNS

- **Phase-transition execution (minor path)** — the five-step archive-and-populate sequence at phase boundary: (a) archive the completed phase's four synthesizing artifacts (`goals.md`, `questions.md`, `research/summary.md`, `design.md`) to the runtime path `docs/qrspi/{slug}/phases/phase-NN/`; (b) read `roadmap.md` to identify next-phase goal IDs; (c) extract entries for those goal IDs from `future-goals.md`, `future-questions.md`, `future-research-summary.md`, `future-design.md`; (d) write the populated next-phase drafts with `status: draft`; (e) invoke `qrspi:goals` for the next-phase Restart Mode pass.
- **Severity classification of phase learnings** — categorize each proposed change as Minor, Major, or Scope Unknown per the Severity Classification table; identify the earliest loop-back target for any Major change.
- **Minor-path artifact updates** — apply approved minor changes to `tasks/*.md` and `plan.md`; transition status to `replan-draft` and back to `approved` on re-approval.
- **Major-path feedback authoring** — write `feedback/replan-phase-NN-round-MM.md`, reset target + downstream artifacts to `status: draft`, invoke the loop-back skill (Goals, Design, Phasing, or Structure — chosen per the Severity Classification table). Major path is unchanged from baseline (loop back to upstream skill on substantive learnings).
- **Marking next-phase drafts** — every populated next-phase artifact carries `status: draft` so the downstream skill (Goals first, then Questions, Research, Design) re-reviews before proceeding.
- **Boundary with Goals: Formal-vs-Idea schema check on `future-goals.md` entries during phase-boundary promotion, plus hand-off report** — Replan applies the Formal-vs-Idea gate to every `future-goals.md` entry: promotes ONLY fully-Formal entries (frontmatter `id:` + `type:` AND all three required subsections `## Problem`, `## Why we care`, `## What we know so far`) and SKIPS partial-Formal and prose-only Idea entries. The hand-off report enumerates promoted Formal entries (by `id:` and `title:`) and skipped entries (partial-Formal with the missing field or subsection named; prose-only Idea with "prose-only Idea" as the skip reason). Canonical contract lives in `skills/replan/SKILL.md` § Boundary with Goals.

### Replan DEFERS

- **Phasing decisions** (slice decomposition, phase boundaries, replan-gate criteria, Iron Laws 1/2 vertical-slice and Phase-1-PoC enforcement) → owned by **Phasing** (`skills/phasing/SKILL.md`). Replan consumes the existing roadmap; it does NOT re-decide which goals belong to which phase or re-author phase boundaries.
- **Authoring of `roadmap.md`** → owned by **Phasing**. Replan READS the roadmap to find next-phase goal IDs; it does NOT write or amend the roadmap. Roadmap edits between phases are a Phasing-owned operation, not a Replan-owned one.
- **Authoring of `future-*.md` artifacts** → owned by **Phasing** (initial pruning) and by the upstream skill on a Major loop-back. Replan READS the future-* artifacts to extract the next-phase entries; it does NOT add new entries to them.
- **Goal-text expansion or new goal creation** → owned by **Goals**. The scope-mapping check (below) makes this explicit: if a proposed change is not covered by existing goal text, classify Major and loop back to Goals — never silently expand.
- **Architecture, file maps, task specs** → owned by Design / Structure / Plan respectively. Replan proposes severity classifications and (on Minor) applies wording/LOC/split changes inside the existing scope; it does NOT re-author these artifacts.
- **Idea formalization** (minting new `id:` values, assigning `type:` fields, authoring `## Problem` / `## Why we care` / `## What we know so far` subsections for prose-only Idea entries or partial-Formal entries) → owned by **Goals** on a subsequent user-invoked run. Replan's Boundary-with-Goals gate identifies which entries need formalization; the formalization work itself belongs to Goals, not Replan.

## Iron Law

```
DO NOT CLASSIFY A MAJOR CHANGE AS MINOR TO SKIP THE BACKWARD LOOP
DO NOT CLASSIFY A SCOPE-UNKNOWN CHANGE AS MINOR
DO NOT UPDATE APPROVED ARTIFACTS WITHOUT USER APPROVAL
```

## Artifact Gating

Required inputs:

- Completed phase code (merged on feature branch)
- All issues found/fixed during phase (from `fixes/` and `reviews/`)
- Remaining task specs (next phase's `tasks/*.md`)
- `plan.md` with `status: approved`
- `design.md` with `status: approved` (phase boundary context and potential updates)
- `phasing.md` with `status: approved` (slice decomposition and phase boundaries — Phasing-owned; Replan READS this as the source of truth for which goal IDs belong to which phase, and which severity-table loop-backs route to Phasing vs. Design)
- `future-goals.md` (if present) — contains Formal goals (approved for future phases with IDs) and Ideas (informal suggestions from Test/Integrate human gates). Read before producing analysis. Formal goals inform phase promotion. Ideas are presented to user as optional additions. If file does not exist, skip silently.

If any required artifact is missing or not approved, refuse to run and tell the user which artifact is needed.

### Config Validation

Apply the **Config Validation Procedure** in `using-qrspi/SKILL.md`. Replan validates `second_reviewer`.

<HARD-GATE>
Do NOT update approved artifacts without user approval of the proposed changes.
Do NOT classify a major change as minor to avoid the backward loop.
Do NOT classify a scope-unknown change as minor — default to most stringent treatment.
Do NOT skip the backward loop for major or scope-unknown changes — cascading re-approval is the invariant.
</HARD-GATE>

## Severity Classification

| Change type | Severity | Loop-back target | Examples |
|---|---|---|---|
| Task spec wording, LOC estimates, test expectations | **Minor** | None — update in place | "Task 7 needs an extra edge case test", "Task 9 LOC estimate should be ~400 not ~250" |
| Add/remove/split/merge tasks within existing slices | **Minor** | None — update plan.md + tasks | "Split Task 8 into 8a and 8b", "Add Task 12 for missed validation" |
| Reorder tasks or change dependencies | **Minor** | None — update plan.md | "Task 10 should run before Task 9" |
| Impact unclear, cross-cutting, or ambiguous scope | **Scope Unknown** | Treat as Major — use most stringent loop-back target | "This might affect file paths or it might not", "Unclear if this changes the API contract" |
| Change file paths or add files within existing slices | **Major** | Structure | "Need a new middleware file not in structure.md" |
| Change interfaces between components | **Major** | Structure | "The API contract for /entries needs a new field" |
| Change technology choice, approach, or architecture | **Major** | Design | "Switch from polling to WebSockets for real-time" |
| Change phase boundaries or rebalance phases (move tasks/goals across phases) | **Major** | Phasing | "Move Task 8 from Phase 2 to Phase 3", "Rebalance Phase 1 to drop Goal G5 into Phase 2" |
| Change vertical slice decomposition (add/remove/regroup slices) | **Major** | Phasing | "Notifications should be its own slice, not part of the social slice", "Merge the messaging and notifications slices" |
| Change per-task test expectations | **Major** | Plan | "Task 5's expected behavior on retry should change to exponential backoff" |
| Change per-phase acceptance criteria | **Major** | Plan | "Phase 2's acceptance block should require notifications to be observable end-to-end, not just persisted" |
| Change project goals or constraints (problem framing, intent, scope, environmental constraints) | **Major** | Goals | "The MVP scope should include notifications, not just messaging" |
| Fundamental re-evaluation of project direction | **Major** | Goals | "We should target mobile-first instead of desktop-first" |

**Classification criteria for Scope Unknown:** Use when the impact of a change is unclear and you cannot confidently classify it as Minor or Major. Default to the most stringent treatment — treat as Major and identify the earliest plausible loop-back target. Do not guess Minor when scope is ambiguous.

**Key rule:** The loop-back target is the **earliest affected artifact**. If per-task test expectations or per-phase acceptance criteria change, loop back to Plan (Plan OWNS acceptance criteria per the strip-from-goals contract; cascades to tasks/`*.md` regeneration). If file paths change, loop back to Structure (which cascades to Plan). If phase boundaries or slice decomposition change, loop back to Phasing (which cascades to Structure → Plan; Phasing OWNS slice decomposition and phase boundaries). If architecture changes (technology / approach), loop back to Design (which cascades to Phasing → Structure → Plan). If project goals or constraints change (problem framing, intent, scope), loop back to Goals (which resets all artifacts to draft — the entire pipeline re-runs).

## Replan Analyzer Dispatch

Dispatch `Agent({ subagent_type: "qrspi-replan-analyzer", model: "sonnet" })` with a prompt containing the path-vs-body split per the agent's dispatch contract:

**Path inputs (the analyzer Reads files under these paths at runtime):**
- `target_artifact`: name of the artifact whose proposed changes are being analyzed (typically `plan` for replan dispatch — orchestrator picks based on context)
- `path_completed_phase_code`: absolute path to the completed phase's source root
- `path_fixes_dir`: absolute path to `<ABS_ARTIFACT_DIR>/fixes/`
- `path_reviews_dir`: absolute path to `<ABS_ARTIFACT_DIR>/reviews/`
- `path_remaining_tasks_dir`: absolute path to `<ABS_ARTIFACT_DIR>/tasks/`

**Wrapped body inputs:**
- `companion_plan`: `plan.md` body wrapped between `<<<UNTRUSTED-ARTIFACT-START id=plan.md>>>` and `<<<UNTRUSTED-ARTIFACT-END id=plan.md>>>` markers
- `companion_design`: `design.md` body wrapped between `<<<UNTRUSTED-ARTIFACT-START id=design.md>>>` and `<<<UNTRUSTED-ARTIFACT-END id=design.md>>>` markers
- `companion_phasing`: `phasing.md` body wrapped between `<<<UNTRUSTED-ARTIFACT-START id=phasing.md>>>` and `<<<UNTRUSTED-ARTIFACT-END id=phasing.md>>>` markers

The path-vs-body split is deliberate: large fan-out inputs (fixes, reviews, completed-phase code) travel as paths; small fixed artifacts travel as wrapped bodies. NO `goals.md` is passed — the analyzer reads plan and design which already incorporate goals; the review subagents below receive `goals.md` separately for consistency checking.

The analyzer task (analyze patterns / propose updates / classify by severity / identify loop-back target) lives in the agent body auto-loaded by the runtime. Zero rules content in main chat for this dispatch.

**Output capture (sequencing dependency).** The analyzer returns its proposed-changes payload **inline in its response** per the agent's output-format contract — main chat captures the response text and feeds it as `artifact_body` to the replan-reviewer + replan-scope-reviewer dispatches in the Review Round below. This is a sequencing dependency, NOT a parallel dispatch: the review round cannot start until the analyzer returns.

**Scope-mapping check (analyzer responsibility — restated for orchestrator awareness):** when the analyzer ties a proposed change to an existing goal, it verifies the goal's problem framing actually describes the proposal's scope. If the proposal's scope is not covered by the existing goal text, the analyzer classifies the proposal as Major (loop-back to Goals). Goal-text changes are Goals' responsibility on the loop-back, never Replan's. (Acceptance-criteria changes route to Plan, not Goals — per the strip-from-goals contract.)

### Roadmap Usage

During phase transitions, Replan reads `roadmap.md` to determine which goals belong to the next phase. Goals for the next phase are promoted from `future-goals.md` (Formal section) into a fresh `goals.md`. The roadmap's current phase pointer is advanced. Each downstream skill checks `future-design.md` and `future-research-summary.md` for pre-existing work on promoted goals (pull model, not push). Note the file naming: the deferred research artifact is the single file `future-research-summary.md` (mirroring the synthesized `research/summary.md`); per-question files under `research/q*.md` are kept as full-corpus reference and are NOT split into a separate deferred directory.

## Review Round

**Compaction checkpoint: pre-fanout.** Reviewer fan-out (Claude + scope + Codex parallels when enabled) reads the analyzer's proposals + `goals.md` + `plan.md` + `design.md` + every prior phase's review findings; saturated context here degrades the severity-classification signal that drives major-vs-minor routing. See using-qrspi `## Compaction Checkpoints` for the iron-rule contract.

From dfrysinger/qrspi-plus, MIT.

More from dfrysinger/qrspi-plus