Discussion: architecture as a project document, separate build plans, and how detailed plans should be #82

New Issue

2026-09-30T13:03:48Z

dev-agent commented

2026-09-30 13:03:48 +00:00

A discussion to settle before implementation. The operator wants to talk this through first, so no decision is recorded here yet.

What prompted it (second live run). The milestone plan from Opus contained the complete implementation and the complete test file, each marked "create it with exactly this content". It also ran its own git checkout -b feat/truncate-helper. The executor's job was reduced to finding paths, pasting, and running the tests.

The cause is the planner prompt (planner.py): "Produce plans that are explicit and low-inference: a materially weaker model will execute them and cannot reconstruct your intent." For a small task, the most explicit plan is the code itself.

Topics

1. Architecture as a checked-in document, separate from build plans.

The architecture (the durable "what and why") would live in the project repo, as docs/Architecture-Build-Spec.md does for Nisse, and change through PRs. The architecture gate could become a PR against the project.
Milestone build plans would become separate, short-lived documents that reference it.
Open: file layout and naming; how the planner reads and updates the architecture doc; what the architecture gate looks like then; and how this interacts with the Gitea plan issue (A4, Part H).

2. How detailed plans should be (undecided):

A. Keep it as now: plans may contain code wherever that's the most precise specification. Reliable, and the plan gate reviews real code.
B. Plans specify, the executor implements: interfaces, behaviour, edge cases and tests as acceptance criteria; code only for genuinely tricky parts.
C. Depends on size: code allowed for tiny changes, specification for anything larger.

Against A:

the expensive model does the implementation, which defeats the planner/executor cost split;
plan approval becomes code review, repeated at the PR;
plans balloon for larger milestones;
the benchmark shows qwen3.8-27b can write this kind of code itself (37/40).

3. An executor capability profile instead of "materially weaker".

Naming the model ("qwen3.8") in the prompt helps little: the planner likely knows nothing reliable about it, and the executor is configurable (A11; tests use Haiku).
Instead, a profile per model, kept in the reviewable YAML config beside the role mapping and filled in from benchmark results:
- its tools, and the consult budget;
- what it sees (the approved plan and its own milestone work, in a 131k window);
- where it's reliable and where it's weak;
- that it can't ask the operator (until #77);
- that branches and PRs are handled for it.
"Materially weaker" is what pushes the planner to over-specify.

4. Plans never manage branches. Git branch steps in plans conflict with the orchestrator's branch handling, and caused #166 to repeat #165's commit. This overlaps #62 (branch at execution start), which is the structural half. The prompt should also stop asking for branch steps.

Related: #62, #77 (conversational agent), #78 (planner transcript), #79 (milestone declarations in the architecture plan), #81 (milestones that change no code).

🤖 Generated with Claude Code

https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

**A discussion to settle before implementation.** The operator wants to talk this through first, so no decision is recorded here yet. **What prompted it (second live run).** The milestone plan from Opus contained the **complete implementation and the complete test file**, each marked "create it with exactly this content". It also ran its own `git checkout -b feat/truncate-helper`. The executor's job was reduced to finding paths, pasting, and running the tests. The cause is the planner prompt (`planner.py`): *"Produce plans that are explicit and low-inference: a materially weaker model will execute them and cannot reconstruct your intent."* For a small task, the most explicit plan is the code itself. **Topics** **1. Architecture as a checked-in document, separate from build plans.** - The architecture (the durable "what and why") would live in the project repo, as `docs/Architecture-Build-Spec.md` does for Nisse, and change through PRs. The architecture gate could become a PR against the project. - Milestone build plans would become separate, short-lived documents that reference it. - Open: file layout and naming; how the planner reads and updates the architecture doc; what the architecture gate looks like then; and how this interacts with the Gitea plan issue (A4, Part H). **2. How detailed plans should be** (undecided): - **A.** Keep it as now: plans may contain code wherever that's the most precise specification. Reliable, and the plan gate reviews real code. - **B.** Plans specify, the executor implements: interfaces, behaviour, edge cases and **tests as acceptance criteria**; code only for genuinely tricky parts. - **C.** Depends on size: code allowed for tiny changes, specification for anything larger. Against A: - the expensive model does the implementation, which defeats the planner/executor cost split; - plan approval becomes code review, repeated at the PR; - plans balloon for larger milestones; - the benchmark shows qwen3.8-27b can write this kind of code itself (37/40). **3. An executor capability profile instead of "materially weaker".** - Naming the model ("qwen3.8") in the prompt helps little: the planner likely knows nothing reliable about it, and the executor is configurable (A11; tests use Haiku). - Instead, a profile per model, kept in the reviewable YAML config beside the role mapping and filled in from benchmark results: - its tools, and the consult budget; - what it sees (the approved plan and its own milestone work, in a 131k window); - where it's reliable and where it's weak; - that it can't ask the operator (until #77); - that branches and PRs are handled for it. - "Materially weaker" is what pushes the planner to over-specify. **4. Plans never manage branches.** Git branch steps in plans conflict with the orchestrator's branch handling, and caused #166 to repeat #165's commit. This overlaps #62 (branch at execution start), which is the structural half. The prompt should also stop asking for branch steps. **Related:** #62, #77 (conversational agent), #78 (planner transcript), #79 (milestone declarations in the architecture plan), #81 (milestones that change no code). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE

dev-agent referenced this issue

2026-09-30 15:50:25 +00:00

Draft: rewrite the architecture (docs/Architecture.md) #83

dev-agent commented

2026-09-30 19:40:49 +00:00

Settled by the architecture rewrite (#83, merged), docs/Architecture.md:

Architecture and build plans as separate documents: D2. The project's ARCHITECTURE.md lives in the repo and changes by PR; build plans are separate, short-lived, and always discussed.
Plan detail: option B. Plans specify behaviour and interfaces, with tests as acceptance criteria, and include code only where it's the clearest specification (D2).
Capability profiles instead of "materially weaker": L9.
Plans never manage branches; the harness owns them: D2, D4.

Implementation will be scheduled in the Development Plan.

Settled by the architecture rewrite (#83, merged), `docs/Architecture.md`: - **Architecture and build plans as separate documents:** D2. The project's `ARCHITECTURE.md` lives in the repo and changes by PR; build plans are separate, short-lived, and always discussed. - **Plan detail:** option **B**. Plans specify behaviour and interfaces, with tests as acceptance criteria, and include code only where it's the clearest specification (D2). - **Capability profiles** instead of "materially weaker": L9. - **Plans never manage branches;** the harness owns them: D2, D4. Implementation will be scheduled in the Development Plan.

dev-agent closed this issue

2026-09-30 19:40:49 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dev/nisse#82