mirror of
https://github.com/abhigyanpatwari/GitNexus.git
synced 2026-08-28 05:25:25 +00:00
830a045911
Every optimization targets a measured fixed-cost component (eval/workflow_bench ground base: workflow arm −211% to −333% vs baseline, all tasks resolved): - Plan form is category-priced: compact form (core sections w/ § anchors preserved, ≤80 lines excl. pack, mini-pack subset of the context pack) for narrow/default categories; the full 13 sections only for deep work (refactor/security/performance/concurrency/architecture). A compact plan outgrowing its cap reclassifies to full rather than overflowing. - Freshness gate is category-priced: compact categories default to accept (source-weighted, refresh only when a graph claim becomes load-bearing); strict stays the default for full-plan categories — the rebuild+re-index was the largest single fixed cost. - Turn economy: per-category tool-call budgets (~10 to ~45; architecture uncapped); budget exhaustion routes open questions to §12 instead of more digging. - gitnexus-work fast path: HEAD == evidence pin → skip all citation re-reading (the pin's entire point); mini-pack fields tolerated. - lfg Lane 1 boundary triage: tasks below the measured ~35-turn boundary get offered gitnexus-work direct mode before the plan lane is spent. Copies re-synced (npm skills/, plugin, ~/.agents); steering + sync guards green. Re-measurement of the workflow arm follows to verify the numbers actually improve. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4.8 KiB
4.8 KiB
Plan document template
Two forms, chosen by the Phase 0 category (form knob overrides): compact
for narrow/default work, full for deep work. Repo-relative paths for all
repo artifacts in both.
Compact form
Same evidence header, then only the load-bearing sections — keep the §
numbers in the headings so gitnexus-work's § references resolve:
# GitNexus Engineering Plan
> Task: <one line>
> Evidence verified at commit <sha>; GitNexus index <...>.
## Objective (§1)
## Current Behaviour (§2–3) — ≤10 lines, architecture folded in
## Findings (§4–5) — only load-bearing, each tagged + tool-named
## Proposed Changes (§6)
## Implementation Sequence (§7) — risks inline as step notes
## Test Strategy (§8)
## Implementation Context (§11) — the mini-pack (see context-pack.md)
## Assumptions and Open Questions (§12)
## Definition of Done (§13)
Hard cap: 80 lines excluding the §11 pack. Anything cut that still matters becomes one line in §12 — never padded prose. A compact plan that outgrows the cap is a signal the task was misclassified: reclassify to full rather than overflowing.
Full form
Fill every section below. If a section is genuinely empty for this task (e.g. no PDG layer indexed), keep the heading and state why in one line — never silently drop it.
Claim tagging. Tag every load-bearing claim with its evidence class:
[verified] (source-read at the pinned commit), [graph] (GitNexus/PDG
output, not source-confirmed), [inferred] (evidence-backed reasoning),
[assumed] (unverified — must also appear in §12). Untagged prose is
narrative, not evidence.
# GitNexus Engineering Plan
> Task: <one line>
> Evidence verified at commit <HEAD sha>; GitNexus index <fresh | refreshed this session (--index-only [--pdg]) | N commits behind, refresh skipped: <reason> | not used>.
## 1. Objective
A concise description of the requested outcome.
## 2. Current Behaviour
Describe the current implementation and execution path.
Include the most relevant symbols, files, and statement-level observations.
## 3. Relevant Architecture
Explain the involved modules, boundaries, dependencies, and established patterns.
## 4. GitNexus Findings
Summarise:
- primary symbols;
- callers and callees;
- impact radius;
- related implementations;
- related tests;
- important cross-module relationships.
## 5. Statement-Level PDG Findings
For each critical symbol, explain:
- relevant statements;
- control dependencies;
- data dependencies;
- state mutations;
- error branches;
- side effects;
- ordering constraints;
- planning implications.
Do not paste an unfiltered graph dump.
## 6. Proposed Changes
For every proposed change include:
- file;
- symbol;
- exact responsibility;
- intended behavioural change;
- dependencies;
- constraints;
- implementation notes.
## 7. Implementation Sequence
Provide an ordered sequence of implementation steps.
Each step must be independently actionable.
## 8. Test Strategy
Describe:
- tests to add;
- tests to update;
- edge cases;
- failure paths;
- regression coverage;
- integration boundaries;
- relevant verification commands.
## 9. Risk and Impact Analysis
Include:
- high-risk symbols;
- downstream consumers;
- compatibility concerns;
- performance concerns;
- concurrency or transaction risks;
- migration risks;
- observability requirements.
## 10. Files Expected to Change
| File | Symbols | Reason |
|---|---|---|
## 11. Reusable Implementation Context
The machine-readable context pack — see `context-pack.md`.
## 12. Assumptions and Open Questions
Clearly separate assumptions from confirmed facts. Explicitly-deferred
follow-up suggestions (adjacent work the task didn't ask for) land here too.
## 13. Definition of Done
Concrete, testable completion criteria.
Composition notes:
- §2/§5 quote source excerpts at most
max_snippet_lines(30) lines each, and only when the excerpt carries the argument. - §4 findings each name the tool call they came from (tool + key args), plus a one-line quote of the result when the plan leans on it — that is what makes a tool claim auditable later. Stale-index or fallback-mode findings are labelled as such.
- §6 changes may only name symbols the ledger marks
source_verified. - §7 steps are ordered by dependency and independently actionable — an executor can stop after any step with the tree still coherent.
- §8 names real, located test files for updates; new tests get concrete scenario lists (input → action → expected outcome). Verification commands must exist AND be runnable: prefer the npm/CI script form that carries its prerequisites (pre-hooks, builds) over invoking underlying binaries directly.
- §9 must account for every direct (depth-1) dependent the impact pass reported.