fix-plan

fix_plan.md / checklist.md schema and lifecycle management. Topics — format ([ ]/[x]/[BLOCKED] markers, Progress/Completed sections), priority (P0-P3 BLOCKED suffix + external/selfable classification), add (Action/Why/How authoring), update (flip marker / append progress note on an existing item), upsert (dup-check → update in place or fall back to add), draft (deferred plan stub → promote via code-workflow), move ([x] → Completed summary, subtree partial completion), sync (gh pr/issue state polling → auto-check), issue-drafts (write → publish → archive → delete), model-triage (fit + dedicated section), completion-criteria (DoD + marker rules). Default (no args): move (or archive-receiver) → format → sync → priority → flowchart-sync, scoped by role-profile (--role=pm|deep|impl). Use when: "fix_plan", "checklist", "BLOCKED priority", "triage blocked", "fix-plan sync", "issue draft cleanup", "fix-plan draft", "fix-plan default", "fix-plan archive", "model triage", "completion criteria", "role profile", "--role", "orca session launch", "fix-plan upsert", "dup check tracker".

Schema and lifecycle management for fix_plan.md (Ralph convention) and checklist.md (non-Ralph workspaces). Vendor-agnostic — extracted from Ralph integration to be reusable across environments.

Topics

Topic	Description	Guide
add	New item authoring schema (Action / Why / How), length budget, deliverable separation (research / plan / checklist split)	add.md
claim	Multi-session in-progress lease: [CLAIMED:<sid>:<ts>] suffix tag on [ ] / [BLOCKED:*:selfable] items, claim→refresh→release lifecycle, stale-TTL takeover — prevents two sessions duplicating the same item	claim.md
completion-criteria	Definition of done per item output type (Why = scope narrative vs How to apply = deliverable), marker transition rules, residual-scope split	completion-criteria.md
draft	Record a deferred plan stub (purpose + defer reason + resume trigger + expected deliverable) in ## Plan Drafts when full planning is postponed; promote to code-workflow research→plan when the trigger fires. Invoked /fix-plan draft	draft.md
flowchart	Priority flowchart (Mermaid graph TD dependency graph) authoring, clean syntax rules (no inline %%), plan document node mapping (llm-wiki/outputs/, .ralph/plan-drafts/) without file:// URLs, and the pm-role default-pipeline sync procedure (drift check against priority-triage output)	flowchart.md
format	Schema: [ ] / [x] / [BLOCKED] markers, Progress/Completed sections, item state changes, section-consistency check	format.md
issue-drafts	Issue Drafts lifecycle: write → publish → archive (.bak/) → delete from fix_plan	issue-drafts.md
model-triage	High-capability model triage: 5 fit categories + anti-fit table + cross-section discovery procedure + dedicated ## <Model> Target Tasks section operation	model-triage.md
move	[x] → Completed summary rules, subtree-move partial completion under unfinished parent, optional abstract RAG dispatch, and detect_bloated_tasks.py automated audit	move.md
priority	[BLOCKED:P0-P3:reason] GitHub-aligned priority suffix + external / selfable reason classification + triage workflow	priority.md
sync	GitHub PR/Issue & Plane REST API state polling (gh CLI + plane_sync.py) → auto-check [ ] → [x] on MERGED PR or CLOSED issue; PR CLOSED-without-merge → [BLOCKED:P2:external]	sync.md
sync-automation	Stop-hook checkpoint nudge — reminds to run sync when a tracker referencing PR/Issue numbers hasn't been synced in a while, without any network call inside the hook itself	sync-automation.md
update	Mutate an EXISTING item in place — flip its marker or append a one-line progress note — via update_item.py, without going around block-direct-checklist-edit.js	update.md
upsert	Dup-check the tracker before authoring — match on Action semantics across all sections, update in place (preserve Why, state priority reclassification) when found, fall back to add's schema otherwise	upsert.md
verify	Cross-check commit-hash/file-path references cited in tracker items against local git/filesystem state before trusting a "still unresolved" claim (distinct from sync's external GitHub polling)	verify.md

Topic Dependencies

text

fix-plan (schema + lifecycle)
  ├─→ (default, no args) → move (archive-receiver) ──→ format ──→ sync ──→ priority ──→ flowchart-sync
  ├─→ format (entry — section structure + markers)
  ├─→ priority (new convention — BLOCKED P0-P3 + reason)
  │     └─→ depends on sync (Step 0: refresh external state before classifying)
  ├─→ add (authoring act-now items)
  ├─→ upsert (dup-check → update-in-place OR fall back to add's schema for a genuinely new item)
  │     └─→ add (fallback path)
  ├─→ claim (multi-session lease) — annotates format's markers; move drops the tag on completion; priority triage excludes fresh-claimed items
  ├─→ model-triage (cross-section discovery → dedicated section; items authored via add's schema)
  ├─→ draft (deferred plan stub → `## Plan Drafts`)
  │     └─→ code-workflow/steps dispatch on promote (research → plan)
  ├─→ move (completion → Completed)
  │     └─→ optional --rag=<skill>:<topic> dispatch for semantic indexing (caller-supplied)
  ├─→ sync (GitHub state polling) — depends on github-flow gh CLI conventions
  │     └─→ sync-automation (Stop-hook nudges this topic when overdue — no direct call dependency)
  ├─→ verify (local git/filesystem staleness check — complements sync's external-state polling)
  ├─→ flowchart (Mermaid priority graph) — step 5 of the default pipeline, drift-checks against priority's output
  └─→ issue-drafts (lifecycle of draft files)

• All topics are independently invocable, except priority which invokes sync as Step 0 (HARD STOP) — triage on stale state is the failure mode the dependency prevents (see priority.md Triage workflow Step 0)
• verify is a recommended pre-check before triaging any [BLOCKED]/[ ] item that cites a specific commit hash or file path — see verify.md
• Default invocation (no args): first runs move (or archive-receiver dispatch), then verifies schema via format, syncs external state via sync, triages blockers via priority, and syncs the ## Flow Chart section's node labels against that triage output via flowchart (pm role only — see "Role-based execution").
• move topic optionally dispatches to a RAG receiver if the caller supplies --rag=<skill>:<topic> — generic skill stays vendor-agnostic; receiver implementation lives in the caller (e.g., ralph wrapper)
• sync topic optionally dispatches to a secondary-tracker receiver if the caller supplies --secondary-sync=<skill>:<topic> — see sync.md "Secondary-tracker sync cadence"
• draft topic dispatches to code-workflow (steps) on promote — turns a deferred stub into a real research → plan
• upsert topic falls back to add's schema when the dup-check finds no matching item — not a separate authoring flow, just the entry point that checks first

Configuration

Option	Default	Description
claim-ttl	4 (hours)	Stale-claim TTL for the claim topic — a [CLAIMED:<sid>:<ts>] lease older than this (or whose session has ended) is takeable by another session. Set via --claim-ttl=<hours>. See claim.md
archive-receiver	(unset)	Optional <skill>:<topic> dispatch for default invocation (no args). When set, the caller routes the source's ## Completed section to this receiver for external archiving (weekly report, postmortem log, RAG store, etc.). Receiver harvests + appends to its own report + removes harvested lines from source. Set via --archive=<skill>:<topic> CLI flag. See "Default invocation" below
completed-archive-period	monthly	Period for the receiver-independent local archive of the ## Completed section — monthly (YYYY-MM) or weekly (ISO YYYY-Www). On the period boundary, older Completed entries move to <tracker-dir>/.bak/<tracker-stem>-completed-<period>.md and are removed from the tracker, keeping the live file small. Set via --completed-archive-period=weekly|monthly. See move.md "Completed-section size management"
rag-receiver	(unset)	Optional <skill>:<topic> dispatch for move topic semantic indexing — set via the --rag=<skill>:<topic> CLI flag on the move topic (see move.md). No env var or config file is consumed by this skill; the caller routes
role-profile	(unset)	Execution-role scoping for the default invocation — CLI --role=<pm|deep|impl>. Values are abstract profile names (pm = mechanical bookkeeping/recording, deep = large-scale classification & audit, impl = implementation); this skill never hardcodes model names. Resolution chain: explicit flag → context self-detection → unset = full pipeline (backward compatible). See "Role-based execution" below
secondary-sync-receiver	(unset)	Optional <skill>:<topic> dispatch for the sync topic — runs a project's non-GitHub backlog tracker (Plane, Jira, etc.) in the same cadence as this skill's GitHub PR/Issue sync, instead of letting it drift independently. Set via the --secondary-sync=<skill>:<topic> CLI flag. No tracker name is hardcoded — the receiver owns all tracker-specific details. See sync.md "Secondary-tracker sync cadence"
task-tracker	fix_plan.md	Tracker filename. Use checklist.md for non-Ralph workspaces

Default invocation (no args)

When /fix-plan is invoked with no args, it must execute the following sequential pipeline (scoped by the resolved role profile — see "Role-based execution" below):

Step 0 — Recency check (HARD STOP, runs before task registration): before registering pipeline tasks, scan the tracker's pinned/header block (if the tracker has one) for a "last full pipeline run" marker left by a prior invocation of this same default-invocation pipeline. If found and it indicates a very recent completion (same calling context, no new external trigger since), report what that run covered and call AskUserQuestion offering: skip entirely (report only) / run selective steps (e.g. Sync only, since external state may have moved) / run the full pipeline anyway. Do not silently start Step 1 when recent-completion evidence is already present in the file being read — the tracker is both the pipeline's operand and, when this marker exists, its own run log. If no marker exists (or the tracker has no pinned block), proceed directly into Step 1 as before — this step is a no-op on trackers that don't use the convention.

Recency-ask answer reuse (HARD STOP — never re-ask a scope question the user already answered): the Step 0 recency ask is a per-day, per-context decision — not a per-invocation ritual. Before calling AskUserQuestion, read the tracker's pipeline log for recency-ask answers the user already gave today in the same calling context: (a) if the user already answered a recency ask today, reuse that answer's pattern (e.g. "core only" → skip the steps that would duplicate a same-day 0-change run) instead of re-asking; (b) an explicit role-flagged re-invocation (e.g. --deep) made after a same-role run already completed today is itself the scope answer — do not ask; skip the pipeline steps that would duplicate that run (report what was skipped and why) and proceed straight to that role's remaining actionable work (for deep, the dedicated model-triage section's executable items; for pm/impl, due REPEAT items and surfaced selfable candidates); (c) re-ask only when external state has plausibly moved in a way the user has not seen (new merges/closes since the last run), or an explicit scope argument conflicts with the logged answer. The user answering the same scope question twice in one day is a defect, not diligence. Step-dedup never exempts queue execution (HARD STOP): what recency-reuse skips is the pipeline steps only — the role's remaining actionable queue (the dedicated deep-audit items, due REPEAT items, surfaced selfable candidates) must still be drained, or explicitly enumerated as user-decision remainders. Closing the run on bookkeeping alone because "today's steps already ran" is a mandate-shrink this clause does not authorize.

1. Move / Archive: Dispatch to the configured archive receiver (or fall back to the move topic) to harvest/cleanup Completed entries.
2. Format: Verify the schema, markers, and section structure of the tracker.
3. Sync: Poll external GitHub states (gh pr view / gh issue view) for referenced issues/PRs to auto-resolve completed ones.
4. Priority: Triage and sort the remaining [BLOCKED] list based on the synchronized states.
5. Flowchart sync: Compare the ## Flow Chart section's node labels and dependency edges against the priority tags just produced in step 4 — update any node whose [P*] label, or whose backing item's resolved/removed state, has drifted from the live tracker. See flowchart.md "Sync procedure".

Recency marker maintenance: upon completing the full pipeline (through step 5, or through the REPEAT cadence check for the pm role profile), stamp/update the "last full pipeline run" marker in the tracker's pinned block with the completion timestamp and the role profile used, so Step 0 of a future invocation can find it. If the tracker has no pinned block, skip this — do not create new tracker structure solely for this marker.

Register BEFORE execute (HARD STOP): before Step 1 (Move) begins — after Step 0's recency check has resolved which steps are actually in scope — TaskCreate (or TodoWrite if TaskCreate is unavailable) must register one task per pipeline step actually being run (Move/Format/Sync/Priority/Flowchart-sync for the full pipeline, fewer for a role-scoped subset or a Step-0-narrowed run — see "Role-based execution" below). A default-invocation /fix-plan run is multi-step by definition; "the tracker looks small" is not an exception. If a TaskCreate call errors, retry it with the corrected parameters from its own error message before any Move/Sync/Priority/Flowchart Edit proceeds — treating a retry as unnecessary overhead and silently dropping tracking is the exact violation this line prevents. Mirrors ~/.claude/skills/wip/SKILL.md "Register BEFORE execute".

Subagent-delegated pipeline runs require artifact verification, not just TaskUpdate trust (HARD STOP): when a caller delegates this default pipeline to a subagent (Agent spawn) rather than executing it directly, a subagent marking its assigned tasks TaskUpdate(status: "completed") is NOT sufficient evidence the corresponding tracker edits actually happened. No whole-pipeline hand-off: never hand the whole registered task set to one subagent call as a single "run pm" prompt — dispatch (or check in on) each step individually, and after each reported-done step, independently re-read the tracker yourself (a git diff/section-length/marker check against the actual file) before treating the next step as safe to start. Before treating any delegated run as done, the delegating caller must independently confirm at least one concrete artifact change per claimed step — e.g. a new ## Pipeline Execution Log entry, a diff in the ## Flow Chart node count, a changed [BLOCKED:P*] count, or a new ## Completed entry. Two consecutive idle/no-evidence status replies from a delegated agent means stop waiting and take the remaining steps over directly, not send a third status request — verify the tracker file directly (line counts, section diffs) and take over the remaining steps yourself if the artifacts show no real change. A subagent's self-reported completion is a claim, not proof. This mirrors a real incident: a subagent given the whole pipeline marked all 6 default-pipeline steps completed while leaving the tracker file byte-for-byte unchanged.

Role-based execution (role-profile)

Plan & Research Reading Prerequisite Gate (HARD STOP): When executing tasks from fix_plan.md or cited plan snippets, the agent MUST first read the full related research document or plan file (plan-*.md, docs/) via view_file before starting any implementation steps (CLI commands, repo renames, code edits).

Premise re-verification (HARD STOP): reading the plan is not enough. Before the first implementation step, re-verify the plan's external premises against primary sources — every issue / PR / release / tracker item the plan cites as a blocker or precondition (gh pr view / gh issue view / the cited tracker line). A status: decided|approved plan may predate the world: a cited external blocker can resolve (or reverse) between authoring and start. This extends draft.md Stage 2 step 1's promote-time re-verification to ALL plan-gated starts, not only draft promotes.

Plan Generation Complete Deep Audit Registration Gate (HARD STOP): When the authoring or revision of any plan document (plan-*.md) is completed, stopping after file creation — leaving the plan with no tracker entry that hands it to the next stage — is strictly prohibited (HARD STOP). The agent MUST immediately register an audit request entry in the tracker's dedicated deep-audit section (## Deep Tasks, or the ## <Model> Target Tasks section described in model-triage.md) with a [BLOCKED:P*:selfable] marker whose priority comes from normal triage (priority.md) and the caller's configured audit_status: pending_* token, citing the plan and research documents. Implementation work may not proceed until the deep profile's audit completes and the entry reaches an audit_status: approved_by_* value, at which point model-triage.md's implementation-queue move obligation applies. Concrete model names stay caller-side — see the role-resolution note below.

The default pipeline is scoped by the execution role, so a high-capability session is not spent on mechanical bookkeeping — and a bookkeeping session does not attempt deep-analysis passes it is unsuited for.

Role resolution chain (first match wins):

1. Explicit --role=<pm|deep|impl> CLI flag
2. Context self-detection — when the invoking agent can identify the model it is running on (from its own runtime context, e.g. a model identifier exposed by the harness) AND the workspace declares a model→profile mapping (a local operating note in the tracker, a project rule — caller-side, never in this skill), resolve the profile from that mapping
3. Neither available → run the full pipeline (backward compatible — unchanged behavior for existing users and environments without role mappings)

Pointer-tracker resolution (HARD STOP): Before concluding "no candidates" for a workspace's local fix_plan.md/checklist.md, check whether its active-work section has been replaced with a redirect note pointing to a parent/org-level tracker (e.g. an HTML comment or line like "this repo's items live in <parent-path> — see there" / "moved to <parent-path>"). If found, resolve the referenced path and treat that parent tracker's own top-level ## sections (not just the specific subsection the note points at) as in-scope for this invocation's Move/Sync/Priority/impl-candidate steps. A redirect narrowing to one subsection (e.g. ## Fable Target Tasks) is not evidence the rest of the parent tracker (## Priority Work, ## REPEAT, ## TODO, etc.) is out of scope — those sections are exactly where pm/impl candidates live.

Full-header self-check (HARD STOP): If you ran grep "^#" (or equivalent) to get the tracker's section list, you must Read every top-level ## section from that list before reporting candidate counts — not just the section you most recently wrote to. Recency (having just edited a section) is not grounds to skip sibling sections; it is exactly the bias that causes a populated ## Priority Work / ## REPEAT section to be missed while a freshly-touched ## Fable Target Tasks gets re-read.

Per-profile default pipeline:

Profile	Steps executed	Skipped (reported as remainder)
pm	move → format → sync → priority → flowchart-sync → REPEAT cadence check (run all due REPEAT items) → Plan Drafts trigger scan (surface, never author — see draft.md "Role ownership")	—
deep	sync (cheap state refresh) → priority (judgment-quality gain) → model-triage re-discovery + plan-audit candidate scan	move, format, flowchart-sync — surfaced as a delegation remainder for a pm session
impl	sync → priority → REPEAT overdue check (run REPEAT items overdue by 24h+) → Plan Drafts promote execution (premise re-verify + code-workflow research→plan dispatch for triggered drafts — see draft.md "Role ownership"), then surface selfable implementation candidates	move, format, model-triage, flowchart-sync
(unresolved)	full pipeline	—

First-edit timebox (impl profile — HARD STOP): an impl-profile run exists to land implementation edits. If N minutes (default 15) elapse after the first tool call with zero deliverable edits (no Edit/Write on a non-tracker file), STOP front-loading (triage reading, option pre-verification, plan re-reads) and either (a) start the smallest viable implementation step now, or (b) report the blocker to the user. Front-loading gates (recency check, full-header read, Plan Reading Gate, premise re-verification) bound what to read — they never authorize unbounded time before the first edit. In high-latency environments (large trackers, heavy hook chains), also batch reads: prefer 1-2 large Read calls over many small shell reads, and keep pre-edit lookup calls to roughly 10 or fewer.

• REPEAT Section Execution Cadence Rule:

  • /fix-plan --pm: Check ## REPEAT section. If any item's due period (its "period" field) has elapsed since its "last run" field, execute it immediately.
  • /fix-plan --impl: Check ## REPEAT section. Execute ONLY items whose due period has elapsed AND has been neglected for an additional 24+ hours (period + 24h overdue). Skip others.

• A skipped step is never silently dropped: the run report must list the skipped steps and their pending workload (e.g. "N completed [x] items awaiting move") so a later pm session picks them up.

• Model names never appear in this skill. The caller-side mapping translates concrete models to pm / deep / impl — the same supply pattern as the --archive / --rag receiver contracts.

pm-profile completion handoff: when a pm role-profile default-invocation pipeline finishes (through the REPEAT cadence check), do not close the turn with an open-ended "what's next" prompt. Reuse the sync/priority state this same run already computed and surface exactly one simple selfable candidate from what the impl row's own candidate-surfacing step would otherwise report — then confirm it via AskUserQuestion (proceed with it / pick something else / skip for now) instead of a generic next-step prompt. This draws from a single already-known role profile's own candidate set computed in this same run, not a speculative multi-source scan — it is a narrower, cheaper handoff than general next-action option construction. If no selfable candidate exists this run, skip this step and close normally.

Simple-vs-session self-check (HARD STOP — run before drafting the pm-profile completion handoff AskUserQuestion, not after): having read this paragraph once is not the same as applying it at the moment the ask is drafted — do not default straight to a "proceed now" option. Explicitly ask: does the candidate touch 2+ files, or does it require authoring/updating regression tests, or is it otherwise impl/deep-tier work rather than a single-file mechanical edit? If yes, it is NOT a simple in-session item — go to the Orca check below before finalizing the ask's options, and do not present "proceed now" as the sole or Recommended option without first completing that check.

Orca session-launch recommendation (conditional on Orca detection): when the pm-profile completion handoff above identifies a candidate that is not a simple in-session selfable item but genuinely needs a deep or impl role session, check whether the Orca IDE runtime (stablyai/orca — see the orca skill) is available: attempt <orca> status --json, resolving the CLI per the orca skill's "Resolve the CLI" convention (ORCA_CLI_COMMAND → orca-dev in a dev checkout → orca-ide outside a managed terminal on Linux → orca).

If Orca is available, add a "launch via Orca" option to the pm-profile completion handoff AskUserQuestion for that candidate — the orca skill's launch topic (worktree create --agent claude --prompt "<candidate + tracker path>") — instead of only surfacing it for later manual pickup.

If the call errors or result.app.running is false, do NOT silently skip — ask direction. Extend the same pm-profile completion handoff AskUserQuestion with these additional options for this state (still one decision, not a second ask):

• Diagnose/install Orca, then retry — point at the orca skill's own troubleshooting ("Resolve the CLI" errors are reported verbatim, never silently swallowed); if a dedicated orca doctor diagnostic topic exists by the time this runs, prefer it
• Use an alternative session-launcher skill already available (e.g. clawo, openclaw) — fix-plan stays abstract here: it names the alternative skill and defers to that skill's own launch/send convention, the same way it already defers to caller-supplied --archive/--rag receivers rather than hardcoding their internals
• Dispatch as a subagent (Agent tool, in-process) — a valid option, but never the Recommended one; session isolation and independent context are worth more than the convenience for deep/impl-tier work
• Fall back to today's surface-only behavior (no session action, just report the candidate) — always available regardless of detected state

Duplicate-check is mandatory before recommending a NEW deep-role launch (HARD STOP) — concurrent deep-role sessions duplicate the same large-scale classification/audit work, which is wasteful (unlike impl, where independent parallel implementation on different candidates is normal and this check does not apply). Before offering "launch a new deep session," list running terminals (<orca> terminal list --json) and filter for one already working this tracker's deep-tier candidates (title/preview matching the tracker path or a deep-role marker — reuse the orca skill's send topic filtering convention, but skip its ORCA_PANE_KEY self-exclusion requirement here, since this is a check, not a delivery). A match found → offer "send to the existing session" (orca skill's send topic) instead of "launch a new one." 2+ matches found → do not auto-pick — list every match as a separate option (same disambiguation rule as orca/send.md).

#	Don't	Do
1	Recommend orca launch for every deep/impl candidate regardless of environment	Detect Orca first (status --json); skip the option entirely if unavailable
2	Launch a new deep session without checking for one already running	orca terminal list --json + title/preview filter first; route to an existing match instead of duplicating
3	Auto-select among 2+ matching running sessions	List every match as a separate AskUserQuestion option — never guess
4	Apply the same duplicate-check requirement to impl launches	impl sessions may run concurrently on independent items — duplicate-check is deep-only
5	Silently skip the recommendation when Orca detection fails	Ask direction instead — diagnose/install Orca / use an alternative launcher (clawo, openclaw) / subagent (not recommended) / surface-only
6	Default the pm-profile completion handoff ask straight to "proceed now" because the candidate seems short to describe	Run the simple-vs-session self-check first — a short description can still be multi-file/impl-tier work; length of the candidate's own text is not the signal

Mandatory Output Reporting Contract (HARD STOP): The agent must physically emit the Step 4 Priority Triage candidate list (P0–P3 sorted by :selfable vs :external) in the visible response text BEFORE marking the task as completed ([x]) or invoking AskUserQuestion. Suppressing Step 4's summary table output or marking tasks completed prior to physical output emission is strictly forbidden.

Receiver contract

The fix-plan skill stays vendor-agnostic — no hardcoded receiver name. The caller (Claude in the user's environment) routes to whichever receiver is registered.

Field	Value
Dispatch flag	--archive=<skill>:<topic> (CLI)
Receiver responsibility	(1) Read source's ## Completed section, (2) Append items to its own report format, (3) Edit source to remove harvested lines
Idempotency	Receiver must be safe to re-invoke — already-harvested items must not double-append
Failure handling	If receiver unavailable / errors → log + fall back to move topic without touching source

Caller auto-dispatch heuristic

The caller decides at invocation time:

1. Check --archive=<skill>:<topic> CLI arg → if present, use it
2. Otherwise scan registered skills for a Completed-archive contract (matching topic name or declared fix-plan-archive keyword in description)
3. Exactly one match → dispatch automatically
4. Multiple matches → ask the user
5. Zero matches → fall back to move topic

Example receivers (illustrative — not bundled)

The following are environments in which an archive receiver might be registered:

Environment	Receiver pattern	What it does
Weekly-report workflow	a topic that ingests fix_plan Completed into weekly reports	Append by ISO-week + remove from source
Postmortem log	a topic that appends to a rolling postmortem document	Append + remove
RAG store	a topic that upserts Completed entries into a vector DB	Upsert + remove

These are examples, not dependencies. The fix-plan skill does not import any of them; the caller supplies the receiver.

Quick Reference

Default invocation

bash

/fix-plan                            # dispatch to configured archive-receiver (or fall back to move)
/fix-plan --archive=<skill>:<topic>  # explicit receiver

See "Default invocation (no args)" section above.

Schema (format)

markdown

# Fix Plan

## Progress

- [ ] {Action}
  - **Why**: {motivation}
  - **How to apply**: {procedure}
- [BLOCKED:P0:external] {Action} (awaiting X)
- [x] {Completed item — pending move}

## Completed

- 2026-06-07 12:00 — {one-line summary} (commit {sha}, PR #{N})

See format.md for full schema.

BLOCKED priority + reason (priority — NEW convention)

markdown

- [BLOCKED:P0:external] PR #45 user merge decision
- [BLOCKED:P1:selfable] consolidate Step 2.4 PR create (branch + body ready)
- [BLOCKED:P2:external] CodeRabbit re-review awaiting

• P0–P3: GitHub priority label-aligned (P0 highest)
• external: true external dependency
• selfable: progressable now (P-rank for immediate action)
• Triage Step 0 — sync external state first (HARD STOP): /fix-plan priority invokes sync topic before classifying — gh pr view <N> + gh issue view <N> on every referenced PR/Issue. Auto-resolves merged/closed entries to [x] so stale items don't get sorted as live BLOCKERs

See priority.md for full convention. When a workspace mirrors backlog into Plane, P0-P3 maps 1:1 onto Plane's native urgent/high/medium/low priority (../backlog/scripts/plane_sync.py's normalize_priority(); see sync.md "Secondary-tracker sync cadence" and backlog/SKILL.md "Plane Issue DELETE Prohibition & Priority Mapping (HARD STOP)").

Add new item

markdown

- [ ] {one-sentence Action}
  - **Why**: {motivation 1-2 sentences}
  - **How to apply**: {procedure / tools / commands}

See add.md for length budget + deliverable separation.

Upsert (dup-check before authoring)

Before writing a new item, grep the whole tracker for its core keywords:

bash

grep -n "<2-3 core keywords>" <tracker-path>

No hit → fall back to add's schema above. Hit on the same Action → update that item in place (preserve Why, add a delta, state any priority reclassification as old → new + reason). See upsert.md.

Claim an item in progress (multi-session)

Re-read the tracker, then stamp a lease tag before starting work so a concurrent session does not duplicate it:

markdown

- [ ] [CLAIMED:<sid>:<YYYY-MM-DDTHH:mm>] {Action}
- [BLOCKED:P1:selfable] [CLAIMED:<sid>:<ts>] {Action}

[CLAIMED] is a lease annotation (not a checkbox state). Completion ([x] → Completed) drops it; a claim older than the TTL (default 4h) or from an ended session is takeable. See claim.md.

Record a deferred plan draft

markdown

## Plan Drafts

- [BLOCKED:P2:selfable] {Purpose — one line}
  - **Defer reason**: {why postponed}
  - **Resume trigger**: {what promotes it}
  - **Expected deliverable**: research | plan | checklist

Invoked /fix-plan draft. Stub only (no full plan) → promote to code-workflow research→plan when the trigger fires.

Plan Drafts are always [BLOCKED:P*:selfable], never [ ] — [ ] would let autonomous loops (e.g. Ralph wrapper) act on the entry, but promote requires a user decision. The reason is always :selfable (body file ready, waiting on a user signal, not on a third party). Priority P0-P3 ranks promote urgency relative to other drafts. See draft.md and priority.md.

Move to Completed

After [x] checked, summarize to one line + move to Completed section. See move.md.

Archive Completed periodically (keep the tracker small)

On a period boundary, move older ## Completed entries to a local partition file so the tracker never bloats:

text

<tracker-dir>/.bak/<tracker-stem>-completed-YYYY-MM.md     # monthly (default)
<tracker-dir>/.bak/<tracker-stem>-completed-YYYY-Www.md    # weekly (--completed-archive-period=weekly)

Receiver-independent (no external receiver needed). Entries before the current period move out; the current period stays. See move.md "Completed-section size management".

Sync GitHub state

bash

gh pr view <N> --json state,mergedAt   # PR
gh issue view <N> --json state,closedAt # Issue

MERGED PR or CLOSED issue → auto [x]. PR CLOSED-without-merge → [BLOCKED:P2:external]. See sync.md.

Issue Drafts lifecycle

issue-drafts/<slug>.md → gh issue create → archive to .bak/ → delete from fix_plan. See issue-drafts.md.

Plane Intake Ingestion Gate for PR & Completed Items (HARD STOP)

Work items backed by GitHub PRs or completed during sessions without a Plane identifier ([ES6KR-<N>], [INFRA-<N>], etc.) MUST be ingested into Plane via Intake (plane_create_issue.py) to preserve historical audit logs and decisions. See backlog skill.

See Also

• github-flow (depends-on) — gh CLI conventions for sync + register
• backlog (depends-on) — Plane issue/intake lifecycle and sync engine
• orca (optional, conditional) — session-launch recommendation for deep/impl role candidates when the Orca IDE runtime is detected; see "Orca session-launch recommendation" above
• Ralph integration is a separate workstream maintained outside this published skill. A Ralph wrapper, when present, owns Ralph-specific concerns: the ## REPEAT persistent-item section, autonomous-loop [BLOCKED] skip semantics, and the caller-side --rag=<skill>:<topic> dispatch (this skill exposes only the abstract flag contract). See the Ralph project's documentation for wrapper details