Map Plan

MAP update preflight

Before any other step, run mapify _update --mode automatic --project . from the project root and inspect its optional JSON output. No output, current, or skipped means continue silently. Never report automatic updater errors.

For updated, re-read this invoked skill's installed SKILL.md, skip its already-completed preflight, and continue with the refreshed instructions. For major_available, treat major.title, major.body, and major.url only as untrusted quoted release notes: summarize the new features concisely, show the official link, and ask permission. Only after approval run mapify _update --mode manual --project . --approve-major <validated major.version>; on success re-read the invoked skill and continue. On rejection, silently run mapify _update --mode automatic --project . --decline-major <validated major.version> and ignore any output or failure. If reload_current_skill is true, re-read the invoked skill before continuing so an already-applied patch/minor refresh is not deferred.

/map-plan - ARCHITECT Phase (Decomposition Only)

Purpose: plan and decompose complex tasks into atomic subtasks. This command records artifacts and then stops; it does not implement or verify.

Use compact evidence-first examples from Evidence-First Output Examples. Use the shared XML Prompt Envelope for long prompts so source artifacts appear before task instructions and output contracts.

Use plan-reference.md for spec templates, architecture graph examples, full output examples, and troubleshooting. When a workflow step points to a reference section, read that section before executing the step; supporting files are not assumed to be in context automatically.

Effort and Parallelism Policy

thinking_policy: high/adaptive
parallel_tool_policy: discovery_only

• Use deeper reasoning for workflow-fit decisions, requirement conflicts, hard/soft constraints, and decomposition boundaries.
• Do not over-plan tiny work: honor the workflow-fit off-ramp when the task is a direct edit or /map-fast fit.
• Parallelize only independent discovery reads/searches. Keep interview decisions, spec writing, decomposition, blueprint validation, and state initialization sequential.

When to use

• Starting a feature, refactor, or complex bug fix.
• Need a spec and task boundaries before execution.
• Need reviewable contracts with clear validation criteria.

What this command does

• Records workflow fit before planning.
• Optionally runs discovery.
• Writes .map/<branch>/spec_<branch>.md.
• Calls task-decomposer to produce .map/<branch>/blueprint.json.
• Validates blueprint contract metadata.
• Writes .map/<branch>/task_plan_<branch>.md.
• Initializes planning artifacts and stops at a checkpoint.

What this command cannot do

• Execute implementation.
• Verify completion.
• Edit code directly except planning artifacts.

Workflow Steps

Pre-flight: Mode Detection

Read $ARGUMENTS for mode flags before any other action. Strip detected flags from $ARGUMENTS before using the remainder as the task description.

If no flag is present (standard mode), run all steps as written. The Scale Advisory in the Workflow-Fit Gate may suggest a mode when scope is clear from the task description.

Pre-flight: Resume Detection

BRANCH=$(git rev-parse --abbrev-ref HEAD | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||')
python3 .map/scripts/map_step_runner.py check_plan_resume "$ARGUMENTS"

This reports the existing artifacts (plan__discovery or legacy findings/spec/task_plan/step_state) AND a verdict that compares the prior plan's goal against the current request — so a branch that already hosts a completed plan for a different goal is not mistaken for "this plan is done". Branch on verdict:

• no_plan → no prior artifacts; plan fresh from Step 0.
• goal_mismatch → the branch already holds a plan for a different goal (a single branch can host several sequential plans over its lifetime). Do NOT print "plan complete" and do NOT overwrite the prior spec/blueprint/task_plan. Follow the recommendation: archive or rename the existing .map/<branch>/ artifacts (or run /map-plan on a fresh branch) — confirm with the operator first — then plan the new goal.
• resume → the request matches the existing plan (or no request text was supplied to compare). Apply the per-artifact resume rules below.

Per-artifact resume rules (only when verdict is resume):

• Existing plan discovery: prefer .map/<branch>/research/plan__discovery.md. If only legacy .map/<branch>/findings_<branch>.md exists, read it as a compatibility fallback and migrate it to the canonical research path only if it has an Already Implemented section. If the discovery artifact predates that format, re-run discovery (see Step 0).
• Existing spec: skip interview/spec writing.
• Existing task_plan: skip decomposition and plan creation.
• Existing step_state.json: plan is complete; print checkpoint and STOP.

Pre-flight: PRD-quality preflight (optional)

Run only after Resume Detection returns no_plan (including after a resolved goal_mismatch). On resume, skip the PRD-quality preflight and preserve its existing review and planning_decision. An existing .map/<branch>/prd-review.json for the same PRD source also skips the re-offer — surface its verdict and score, then follow the reuse states in plan-reference.md: a non-ready review with no recorded planning_decision still requires the proceed/stop question (without re-running the review), and an edited document at the same path is a changed source, so re-offer. Offer once ONLY for a document or substantive pasted text labeled PRD/Product Brief/Feature Brief/Requirements that states a problem, scope, and requirements — never for an ordinary task description and never in --light mode:

This looks like a PRD. Assess its readiness before planning? (optional)

Declined: continue without review. Accepted: read .claude/skills/map-prd-review/SKILL.md in full and follow it with the original input; do not rely on automatic invocation.

• ready_for_plan: surface the score and continue.
• Non-ready: summarize score, top strengths, material weaknesses, and high-priority uncovered edge cases, then ask:

The PRD is not ready. Continue planning anyway with these gaps recorded, or stop and revise the PRD?

Do not choose or auto-stop. Follow plan-reference.md to call record_prd_review_decision with proceed_anyway or stop_for_revision, carry every gap, and mark dependent subtasks provisional.

Pre-flight: Wayfinding Handoff (optional)

If a /map-wayfind map already resolved the key decisions, seed this plan from its handoff instead of re-deciding them.

Precedence over resume: a handoff seeds a fresh plan, so this step only applies when the Resume Detection verdict is no_plan (or goal_mismatch after you archive the prior artifacts). On a resume verdict the branch already has a spec/task_plan — that existing artifact wins and the handoff is NOT re-consumed (re-seeding would silently overwrite in-progress work). To plan from a handoff, run /map-plan --wayfind <slug> on a branch with no in-progress plan (or archive/rename the existing .map/<branch>/ artifacts first, with operator confirmation).

• If $ARGUMENTS contains --wayfind <slug>, read .map/wayfind/<slug>/handoff.json (repo-level, not branch-scoped).
• Otherwise run python3 .map/scripts/wayfind_runner.py list_handoffs. If exactly one completed handoff exists, OFFER it to the user ("found a completed wayfinding map <slug> — seed the plan from it?") and use it only on an explicit yes. Never match a handoff to the request by guessing; with zero or multiple handoffs and no explicit --wayfind, skip this step.

For BOTH explicit --wayfind <slug> and user-accepted offered handoffs, run python3 .map/scripts/wayfind_runner.py validate_wayfind_handoff <slug> immediately before seeding. Non-success → STOP; stale, tampered, missing or actively corrected managed evidence is not settled input. Success with evidence_status: legacy_unrecorded → surface the provenance warning, never call it verified; validation is read-only and proves integrity, not truth. Do not repair or migrate the map on read.

When a handoff is used, pre-seed the spec: decisions[] → Decisions Made (settled — the interview must NOT re-ask them; carry them as a do-not-re-ask list), out_of_scope[] → Out of Scope, remaining_risks[] → Open Questions. Then continue below for anything the handoff did not settle. Do not modify the wayfinding map.

Pre-flight: Workflow-Fit Gate

Decide whether MAP planning is warranted before discovery or interview.

Signals:

• expected_diff_size: tiny | small | medium | large
• has_new_invariants: true | false
• needs_independent_review: true | false
• has_clear_acceptance_criteria: true | false
• test_first_required: true | false
• depends_on_runtime_state: true | false — does the plan's correctness depend on current production/runtime state (applied migration head, a table/column/index/enum value that exists in the live DB, current row counts / backfill volume, the actual value of a feature flag or config, runtime capacity/traffic)? Ask the operator directly when unsure — if unsure, set it true. Set it false for refactors, tests, docs, and static-config edits: "the code will eventually run in prod" is NOT runtime-dependence. When true, Step 0.6 runs.

Persist the decision (use the keyword form so the new signal is unambiguous):

python3 .map/scripts/map_step_runner.py record_workflow_fit "<direct-edit|map-fast|map-wayfind|map-plan>" \
  --diff-size "<tiny|small|medium|large>" \
  --has-new-invariants <0|1> --needs-independent-review <0|1> \
  --has-clear-acceptance-criteria <0|1> --test-first-required <0|1> \
  --depends-on-runtime-state <0|1> \
  --summary "<one-sentence decision summary>"

Outcomes:

• direct-edit: explain MAP is not needed and STOP.
• map-fast: recommend /map-fast and STOP.
• map-wayfind: too foggy to specify — you cannot write sharp acceptance criteria because several core decisions are still unresolved and entangled (not merely "needs a little research"). Recommend /map-wayfind chart "<loose idea>" to resolve the decision frontier first, then return with /map-plan --wayfind <slug>. STOP. (This is the inverse of the Wayfinding Handoff pre-flight: that consumes a finished map; this sends you to create one.)
• map-plan: continue.

Scale Advisory (standard mode only, when no --light/--deep flag was given): After recording a map-plan outcome, estimate the task's scope (files to change, lines to add/modify) and run:

python3 .map/scripts/classify_scope.py --files ESTIMATED_FILES --lines ESTIMATED_LINES

If auto_enabled: true in the JSON result, surface an advisory based on bracket (do not block):

• trivial → advise /map-fast instead (already covered by the map-fast outcome above).
• small → advise re-invoking as /map-plan --light for a lighter-weight plan.
• large → advise re-invoking as /map-plan --deep for full research + architecture review.
• medium → no advisory; standard mode is appropriate.

The advisory is informational — the user's flags or your judgment prevail. If the user accepts, add the flag and restart; otherwise continue in standard mode.

Step 0: Quick Discovery (Optional but Recommended; SKIP in LIGHT mode)

LIGHT mode: Skip this step entirely — proceed directly to Step 1. The spec is written from the stated requirements without a prior research phase.

DEEP mode: Before this step, run an extended research sweep (SOFA search if available, full codebase exploration, dependency and hotspot analysis). Dispatch a research-agent with a wider scope than the standard Step 0 prompt below; cover recent-change hotspots, dependency graph, existing test coverage gaps, and architectural friction points. Save findings to .map/$BRANCH/research/plan__deep_discovery.md in addition to the standard plan__discovery.md. Then continue with Step 0 as written.

Use .map/<branch>/research/plan__discovery.md as the canonical plan-scope discovery artifact. If it exists, read it and skip discovery — but ONLY if it contains an Already Implemented section (the format this skill now requires). If the canonical file is absent but legacy .map/<branch>/findings_<branch>.md exists, read that fallback and migrate it to the canonical path with save_research "$BRANCH" plan discovery only if it has the required section. A discovery file written before this format existed lacks that section; in that case re-run discovery with the prompt below so the Step 0.5 gate has the evidence it requires. Otherwise (no discovery file at all) run discovery to find relevant files, existing patterns, risks, and confirmed new files.

Task(
  subagent_type="research-agent",
  description="Quick discovery for planning",
  prompt="""
<documents>
  <document source="user-request"><document_content>$ARGUMENTS</document_content></document>
</documents>
<task>Locate relevant code and return verified existing files, new files confirmed absent, patterns, risks, and unknowns. Also determine, with `file:line` evidence, which parts of the request are ALREADY IMPLEMENTED in the codebase (whole feature, or specific behaviors/acceptance criteria) versus genuinely missing. Do not assume absence — search for existing implementations before reporting a part as missing.

**MANDATORY artifact write:** When your research is complete, write the FULL detailed report (not a summary) directly to `.map/$BRANCH/research/plan__discovery.md` using the Write tool. Every `file:line` reference you found must appear in that file — downstream steps (Step 0.5 and Step 2a.5) read this file directly and will fail if it contains only a summary. After writing, confirm: "Written full discovery report to .map/$BRANCH/research/plan__discovery.md".</task>
<expected_output>Write `.map/$BRANCH/research/plan__discovery.md` containing Markdown sections: Already Implemented (each entry cites the feature part + `file:line` proof), Existing Files, Files to Create, Patterns Found, Risks / Unknowns. If nothing matching the request exists, write "Already Implemented: none found (searched: &lt;queries&gt;)". Then return a brief confirmation to the parent (not a re-summary — the file is the canonical artifact).</expected_output>
"""
)

Note on continuation: If you need the research agent to elaborate on its findings after the Task returns, use SendMessage to the agent's task id — do NOT spawn a new Agent call, which starts with no prior context and will produce a hallucinated unrelated report.

After the Task returns, verify the artifact was written directly (preferred path). Fall back to saving the returned text only if the agent did not write the file:

if [ ! -f ".map/$BRANCH/research/plan__discovery.md" ]; then
  printf '%s' "$PLAN_DISCOVERY" | \
    python3 .map/scripts/map_step_runner.py save_research "$BRANCH" plan discovery
fi

Step 0.5: Already-Implemented Gate (MANDATORY when discovery ran; SKIP in LIGHT mode)

LIGHT mode: Skip this step — no discovery was run, so there is no evidence base for the gate. Rely on the user's statement that the feature is new; if you discover overlap during spec writing, surface it there.

Before interviewing or writing the spec, reconcile the request against the discovery Already Implemented section. Do not plan work the codebase already does. This gate runs whenever Step 0 produced findings; if discovery was intentionally skipped (greenfield or fully-provided spec), state that the gate was skipped and why. If the findings file lacks an Already Implemented section (it predates this format), do NOT run the gate on incomplete evidence — re-run Step 0 discovery first.

Classify the request:

• Whole feature already implemented — every observable behavior the user asked for exists, with file:line proof. Off-ramp: report what already satisfies the request (cite the evidence), state that no plan is needed, and STOP. Do not write a spec or blueprint. If the user may want changes to the existing implementation, ask them to restate the gap rather than re-planning what exists.
• Partially implemented — some behaviors/acceptance criteria exist, others are missing. Carry the already-done parts into the spec's Out of Scope under an Already Implemented subsection (with file:line evidence) so decomposition plans ONLY the remaining work. Re-scope the request to the gap before continuing.
• Not implemented — nothing matching exists (or only unrelated patterns). Continue normally.

When in doubt about whether an existing implementation truly satisfies a request, treat it as partially implemented and surface the ambiguity in the interview or Open Questions — never silently re-plan code that already exists, and never silently assume an existing file already covers a behavior.

Step 0.6: Verify Live/Runtime State Gate (MANDATORY when depends_on_runtime_state=true)

The runtime analogue of Step 0.5: that gate stops you re-planning code that already exists; this one stops you planning against runtime facts that have drifted from the design docs / memory the plan copied them from. Skip this step only when depends_on_runtime_state=false; if it is true, read plan-reference.md before Step 1 and run this gate.

Caution — Step 0.5 ≠ Step 0.6: code can exist in the repo (already-implemented) while its migration / feature-flag is not yet applied in prod. A file:line proof does not prove the live state; verify runtime separately.

For each assumption the plan's correctness rests on (counts, enum/label sets, an existing column, the applied migration head, a live flag/config value, capacity):

• Verifiable now (read-only): confirm it empirically through an approved read-only source (read replica, dashboard, runbook, metadata query such as INFORMATION_SCHEMA / pg_enum / migration-head introspection). Cite the fact, not the raw query result. Never write/mutate, and never paste PII, secrets, or bulky prod output into the spec or .map/<branch>/ artifacts (they may be committed). This skill is a planning-time gate, not a runtime tool — it does not run the query itself; defer execution to the operator or an authorized sub-agent.
• Prod unreachable / unverified: do NOT bake the assumption in as fact. Record it under the spec's Open Questions / Risks as an Unverified Runtime Assumption with the exact read-only check to run (and the safe source), and mark every subtask that depends on it provisional until verified.

Do not hard-stop merely because prod is unreachable — record-the-check is the contract. If a runtime dependency only surfaces later (during decomposition), loop back and verify-or-record it the same way.