/gitnexus-plan

name: gitnexus-plan
description: 'Use when you need a deep, implementation-ready engineering plan for a code change — built from GitNexus graph intelligence, statement-level PDG analysis, and targeted source verification, compact enough that an implementation agent can start without re-investigating. Also strengthens existing plans via Deepen mode. Examples: "/gitnexus-plan Add retry support to the ingestion pipeline", "/gitnexus-plan deepen docs/plans/<plan>.md", "plan this change using the knowledge graph".'

gitnexus-plan — implementation-ready engineering plans

Produce an implementation-ready plan for an engineering task. GitNexus is the navigation layer (where to look), statement-level PDG is the constraint layer (what gates and feeds the behavior), and your native targeted source reads are the verification layer (what is actually true right now). The output is a plan document plus a compact, machine-readable **implementation context pack** that a follow-up implementation agent (`gitnexus-work`, or any executor) can consume without repeating the investigation.

/gitnexus-plan <task description>
/gitnexus-plan impact_depth:3 depth:deep <task description>   # knob overrides, see Configuration

**This skill plans. It never implements.** Do not modify production code, tests, or configuration while running it. The only repository file it writes is the plan document (a working ledger kept outside the repo is fine). The only other permitted state change is an index refresh via `analyze --index-only`, which writes only the `.gitnexus` index store. It must not build analyzer `dist/` output and must not mutate source, tests, configuration, or evaluation data. Stale analyzer provenance is disclosed as a source-weighted limitation, never repaired by a planning run.

Hard rules

• **Ledger first.** Before every GitNexus call and every repo file read, check

the context ledger. Never repeat a query or reread an unchanged range that already answered the same question (allowed repeats are defined in `references/context-ledger.md`; this skill's own reference files are exempt from ledger bookkeeping).

• **Every graph query answers a named planning question.** Record the question

and the conclusion in the ledger. No exploratory dredging.

• **Source beats graph.** The graph navigates; current source is authoritative.

Verify before asserting (see Phase 4). Comments are the weakest evidence — never stronger than executable code.

• **No fabrication.** Never invent symbols, filenames, test names, tool

results, or PDG edges. Unknowns go to _Assumptions and Open Questions_.

• **No scope creep.** Adjacent refactors the task didn't ask for go to plan

§12 as explicitly-deferred follow-ups, not into Proposed Changes.

• **Pin working-tree evidence, not only HEAD.** Every plan form carries the

versioned global dirty digest and sorted cited-path manifest defined in `references/context-ledger.md`. Generate it only with the portable helper and byte contract in `scripts/evidence-provenance.mjs` and `references/evidence-provenance.md`; never reimplement the digest.

• **Write the plan only through the helper.** The generated-plan path is a

normalized repo-relative `docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-slug>.md` path. Compose the complete UTF-8 document in memory or in a scratchpad outside the target repo, then pass it on stdin to the helper's `write-plan` command. Never write the destination directly or fall back to an external output path when the safe writer fails.

• **Read an existing plan only through the helper.** Deepen must invoke

`scripts/evidence-provenance.mjs read-plan`, parse the exact decoded `plan_bytes_base64` from its descriptor-anchored receipt, and retain that receipt's canonical `generated_plan_path` and `plan_digest` as one binding. Never parse a direct lexical-path read or apply one plan's digest to another path.

• **Stop when you have enough.** Sufficient evidence ends exploration; plans

do not improve monotonically with tokens spent.

Phase 0 — Parse and classify

Read `references/context-ledger.md` and open the ledger with the task: original request, interpreted goal, acceptance criteria. Classify the task:

| Category | Posture (depth · plan form · tool-call budget · freshness) | | ------------------------------ | -------------------------------------------------------------------------------- | | Bug fix (local) | Narrow, 1–2 primary symbols, `impact_depth` 1 · compact · ~15 · accept | | Feature | Default knobs · compact · ~30 · accept | | Refactor / shared API change | Impact mandatory, `impact_depth` 3 · full · ~45 · strict | | Performance | Default + performance PDG mode (`references/pdg-slice.md`) · full · ~45 · strict | | Security | Default + security PDG mode + `explain` taint findings · full · ~45 · strict | | Dependency upgrade / migration | Impact + compatibility focus; PDG rarely needed · compact · ~20 · accept | | Concurrency / transactional | Control-flow + state-mutation PDG focus · full · ~45 · strict | | Test improvement / docs | Narrowest: usually no impact or PDG pass · compact · ~10 · accept | | Architecture change / spike | Widest: clusters + processes first · full · no cap · strict |

The category posture overrides the Configuration baseline; explicit `key:value` invocation knobs override both. A task matching several rows combines them: take the widest depth, union the focus areas.

**Seeded evidence.** When a completed investigation already supplies verified findings — a finished review, a triage document with `path:line` anchors and named failing scenarios — open the ledger FROM it: cite the source document as the