The Estimate#105
Conversation
plugin.json was bumped to 2.1.1 but marketplace.json was missed. Closes nelson-76d.
The README pinned to v1.7.0, which makes the project look stale now that 2.1.1 is out. Generalise to 'recent releases'. Closes nelson-zlf.
11 identical empty scaffolds (differing only by directory-named H1) were committed across the repo. The codemap agent regenerates these on demand, so they add noise with no value. Removed. If someone runs the codemap agent and wants the output tracked, they can commit the populated file then. Closes nelson-2a2.
The script imported nelson_conflict_scan, which lives in skills/nelson/scripts/. Running the tests from the root scripts/ directory raised ModuleNotFoundError because that directory never had conflict_scan alongside it. Moves both the script and its test into skills/nelson/scripts/, updates the in-file docstring paths and README path references. Closes nelson-qns.
Adds a conftest.py that loads count-tokens.py via importlib (the hyphenated filename blocks ordinary imports) and a test file covering count_tokens_from_jsonl, count_tokens_heuristic, hull_integrity_status, build_report, and scan_squadron. Tests exercise existing behaviour only; no source changes. Closes nelson-339.
The root scripts/ directory is now covered by tests (see scripts/test_count_tokens.py and the relocated conflict_radar tests). Wire it into the CI test job so regressions are caught. Closes nelson-2q9.
Introduces a new planning phase between Sailing Orders and Battle Plan, grounded in the Royal Navy's 7 Question Maritime Tactical Estimate. Covers the interactive flow, acceptance criteria on effects, intent propagation to agents, and adaptive planning.
Introduces a new ESTIMATE phase grounded in the Royal Navy's 7 Question Maritime Tactical Estimate (7QMTE). Nelson now covers the analytical front end — reconnaissance, intent, effects, terrain, forces, coordination, control — before work begins, instead of jumping from orders straight into a battle plan. Why: Nelson has been strong at execution but thin at deliberate planning, leaving users to reach for planning-first tools and hand off mid-mission. The Estimate closes that gap so the framework is a single continuous voice from mission brief to stand-down. Changes - Phase engine: new ESTIMATE phase with TeamCreate/TaskCreate blocked (Agent permitted for Q1 Explore dispatch); exit via estimate.md or estimate_skipped flag. - Opt-out: skip-estimate --reason subcommand for trivial-scope missions. - Telemetry: estimate-outcome subcommand with atomic file-locked appends to estimate-outcomes.json; validates pass/fail/not-verified across test/type-check/lint/review/visual methods. - Fleet analytics: new estimate-outcomes metric with pass rates by method and per-mission; included in --metric all dispatch. - Docs: new the-estimate.md reference and estimate.md template; battle-plan template gains commander's intent and inherited acceptance criteria; SKILL.md restructured into eight steps with Conduct The Estimate at Step 2. - Tests: 268 tests pass, including new happy-path and opt-out E2E suites.
|
I think it sounds like a good idea - I agree, planning is where Nelson falls short. I usually write obsessively detailed design specs, so it hasn't really been an issue for me, but I definitely think it could be a beneficial feature to implement! |
- CLAUDE.md, AGENTS.md, README.md: update six-step references to eight-step; add missing admiralty template entries and the-estimate.md to project structure tree - SKILL.md: fix skip-estimate path to include both advance calls (SAILING_ORDERS→ESTIMATE→BATTLE_PLAN); clarify exit validator wording - .markdownlint-cli2.yaml: ignore docs/superpowers/plans/ (generated plan artifacts) - test_nelson_phase.py: remove duplicate empty TestFullLifecycle stub
- nelson_data_lifecycle.py: remove hardcoded "phase": "BATTLE_PLAN" from cmd_plan_approved and _finalize_plan — the phase engine is now the sole authority for phase transitions - nelson_data_fleet.py: replace hardcoded status/method tuples in _compute_estimate_outcome_analytics with canonical constants from nelson_data_utils (VALID_ESTIMATE_OUTCOME_STATUSES/METHODS) - test_nelson_phase.py: add 6 tests for BATTLE_PLAN and PERMISSION tool blocking (Agent, TeamCreate, TaskCreate); update approve_plan helper to set phase via phase engine; update test_plan_approved_preserves_phase - test_nelson_data.py: replace os.chdir with subprocess cwd parameter in TestStatus tests to prevent working directory leaks on failure
Aligns _file_lock with the pattern already used in nelson-phase.py's _append_event — clean up the lock file from disk after releasing the fcntl lock and closing the handle.
Thanks @JG1995 for the feedback - sounds like it would be worth proceeding. |
Take main's version bump (2.1.2) for marketplace.json. All other files merged cleanly.
| - Split mission into independent tasks with clear deliverables. | ||
| - Map the dependency graph: enumerate units of work that can run without shared state or ordering constraints. Each independent unit receives its own captain. Only group tasks onto one captain when they share files, require sequential ordering, or the context-setup cost demonstrably exceeds the work itself. | ||
| - The default is one captain per independent task. Grouping is the exception and requires a concrete reason. | ||
| - If cost-savings is a priority, also consider task inputs — avoid multiple agents independently loading the same large inputs into their contexts. |
There was a problem hiding this comment.
Looks like this will get lost. I have seen nelson provide several ships tasks that pulled some program documentation and a checklist required by the program. 22,400 words or roughly 80k tokens on a 200k token limit. Having 3-4 ships do that isn't saving costs if fewer ships could cover the work without bending 1 ship per independent task too out of proportion.
There was a problem hiding this comment.
Good catch — this was unintentional. The bullet got swept away when the section was rewritten to inherit from The Estimate. Restored in 77f16f2.
LannyRipple
left a comment
There was a problem hiding this comment.
I like this a lot. It hadn't occurred to me since I don't use superpowers but I do start with my intent, have the agent look around and ask me questions to tease out requirements and then ask it to present a plan for review. I then have it implement the plan using nelson for coordination (with cost savings enabled. :)
After this change can give my intent and expect the rest to just flow. Checkpoint 1 is the perfect point where I can ask, "Let's discuss additional requirements since you found XYZ during Recon." The Checkpoint discipline feels correct to me. If the agent wants to just show me what it found we're working with a tiny mission or a very obvious "Do A, B, C, each feeding into the next."
One thing The Estimate will do is further reduce the likelihood of every seeing Royal Marines. That's not a bad thing but they exist to catch those, "We didn't plan well enough moments", and now we'll almost certainly be planning well enough. If Nelson ever gets pointed at a moving target they would be invaluable but I'd be surprised (horrified?) if my codebase changed out from under me.
I did have one comment about a cost-savings instruction that looks like it will get deleted. I'd ask for a double-check if that was intentional or just got caught up in the block of text. That's in SKILL.md, 3. Draft Battle Plan.
The cost-savings bullet ("avoid multiple agents independently loading
the same large inputs") was inadvertently dropped when Step 2 was
rewritten to inherit from The Estimate. Restored in Step 3.
Addresses review feedback from @LannyRipple on PR #105.
Thanks for the feedback @LannyRipple - great point about the Royal Marines. Sounds like they will only ever be deployed in unusual circumstances. Let's keep an eye on it and perhaps see if there's a need for more regular deployment. Otherwise keeping them in the back pocket may just be the natural consequence of better planning as you point out. Good catch on the cost savings, not sure what happened there, I put it back in. I'll merge this PR in now and make a new release. Thanks again. |
Summary
Implements The Estimate — a new phase between Sailing Orders and Battle Plan — grounded in the Royal Navy's 7 Question Maritime Tactical Estimate. Executes the design in
docs/plan-the-estimate.md.Why: Nelson has been strong at execution but thin at deliberate planning. Many people (myself included) use superpowers or a similar "pre-execution" skill before running Nelson. This change aims to address that gap and move Nelson towards being a full lifecycle tool.
@LannyRipple @popey @JG1995 @EmanuelFaria I would be immensely grateful for your thoughts on this new direction of travel as it is a significant change.
What changed
nelson-phase.py): ESTIMATE slotted between SAILING_ORDERS and BATTLE_PLAN.Agentallowed (Q1 dispatches Explore);TeamCreate/TaskCreateblocked. Exit viaestimate.mdorestimate_skippedflag.nelson_data_lifecycle.py):skip-estimate --reasonsubcommand writesestimate_skipped: trueontosailing-orders.jsonand logs an event.estimate-outcomesubcommand): atomic file-locked appends toestimate-outcomes.json; validatespass|fail|not-verified×test|type-check|lint|review|visual. Captains record outcomes at point of verification.nelson_data_fleet.py): newestimate-outcomesmetric reports pass/fail/not-verified totals, per-method breakdown, per-mission pass rates; included in--metric all.references/the-estimate.md— full conducting reference (7 questions, two-checkpoint flow with three-condition collapse rule, Q1 Explore-dispatch guidance, addendum protocol, voice direction).references/admiralty-templates/estimate.md— ~25-line H2 skeleton with effect sub-example.references/admiralty-templates/battle-plan.md— prepended commander's intent block; added inherited acceptance criteria field per task.SKILL.md— restructured to eight steps with Conduct The Estimate at Step 2; pruned analytical bullets now covered by Q4-Q7; added elegant-prose direction.Test plan
skip-estimate,estimate-outcomevalidation), fleet analytics aggregation.init→ advance → write estimate.md → advance → tasks → squadron → outcomes × N → stand-down →analytics --metric=estimate-outcomesreports correct rates.init→skip-estimate→ SAILING_ORDERS → ESTIMATE → BATTLE_PLAN withoutestimate.md.scripts/check-references.sh— all cross-refs valid.Reviewer notes
docs/plan-the-estimate.md(polished on this PR — checkpoint discipline, file layout, opt-in prompt made concrete).estimate_skippedstill advance onceestimate.mdexists; missions withoutestimate-outcomes.jsonare read as empty lists by the fleet analytics.estimate_skipped,estimate_outcome_recorded.