fix-plan

Fix Plan

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 Dependencies

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)
  ├─→ 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=: 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=: — 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=: — 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

Configuration

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.

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).

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= 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 — see there" / "moved to"). 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:

• 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.

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.

Caller auto-dispatch heuristic

The caller decides at invocation time:

1. Check --archive=: 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:

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

Quick Reference

Default invocation

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

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

Schema (format)

# 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)

- [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 + gh issue view 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.

Add new item

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

See add.md for length budget + deliverable separation.

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:

- [ ] [CLAIMED::] {Action}
- [BLOCKED:P1:selfable] [CLAIMED::] {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

## 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:

/.bak/-completed-YYYY-MM.md     # monthly (default)
/.bak/-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

gh pr view  --json state,mergedAt   # PR
gh issue view  --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/.md → gh issue create → archive to .bak/ → delete from fix_plan. See issue-drafts.md.

See Also

• github-flow (depends-on) — gh CLI conventions for sync + register
• 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=: dispatch (this skill exposes only the abstract flag contract). See the Ralph project's documentation for wrapper details