Front-load rule: trigger on any consequential claim, and give it a stopping condition #977

New issue

Closed

opened 2026-08-09 02:28:37 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-09 02:28:37 +00:00

Member

Problem

The rule already exists and did not bind. AGENTS.md:195 at e7c8e559 reads:

Front-load the context you know you need

Naming a gap is not closing it. When a convention, schema, or subsystem wiring is discoverable in the repo, a skill, or a doc, read it before planning. Before the first edit, list the conventions and subsystems the work touches and confirm you have read each one.

A narrowed scope does not narrow the context budget. The first instance of a pattern needs the most grounding, because that first entry sets the schema everything after it copies.

A single strats session on 2026-08-07 produced four failures this rule was supposed to prevent. All reversible, all caught, which is why they are usable material rather than an incident:

Wrote "information still needed: date, format, length, deadline" into two issues and stopped. Every fact was in an unread email.
Made campaign-level claims about two speaking engagements without measuring their audience. The numbers took four tool calls once attempted.
Concluded a profile "exists nowhere in the portfolio" after searching issues and repository metadata. It had been on main for two days. The tree was never read.
Named an issue and a PR the critical path for a dated commitment, from issue prose alone. The diff showed the branch reverted an architecture main had deliberately removed. The conclusion was not merely unsupported, it was backwards.

The shared root: an artifact describing a thing was accepted in place of the thing. Issue text for code, commit subjects for diffs, metadata for contents.

Why the existing rule did not bind

Diagnosed in coilyco-flight-deck/agent-compose#248, and it resolves to both causes:

The trigger is edit-shaped. "Before the first edit" is a trigger a role writing an assessment, a ranking, or a verdict never reaches, so the rule reads as somebody else's.
There is no stopping condition. It says to read what you need and offers no test for whether you have.

What this issue takes on

agent-compose built a fixed version of this as role doctrine, then found that half of it is not role-scoped at all. That half belongs here, and lands with the two fixes intact:

The trigger becomes any consequential claim, not any edit. A claim is consequential when a reader could act on it or when it enters a durable artifact.
Prefer the thing over a description of the thing. Code over the issue describing it. The diff over the commit subject. File contents over metadata or a search hit. Raw responses over summaries.
An identified gap is a task, not a disclaimer. Recording that information is still needed and stopping is a failure whenever the information is reachable with the access already held.
A stopping condition that can be checked. Before delivering, every consequential claim either names the source that was opened, or is marked as inference with the observation that would settle it. Unavailability never silently promotes a guess into a fact.
One modality is not proof of absence. Searching issues establishes nothing about a repository tree, and a single empty query is not a negative result.
Bounds. Acquisition reaches only sources that would change a specific pending claim or decision. Curiosity is not a warrant. Cost scales with stakes. It grants no new authority, and sending, publishing, and destructive actions stay gated exactly as they are.

Explicitly not in scope

Seeking validation from outside your own frame. That behavior is role-allocated, not universal, and stays in agent-compose as a boundary held by the Executive Strategist. Six roles are chartered to stay inside the local frame: QA works to a fixed acceptance boundary, Designer works from Kai's supplied style, and Engineer, Ops, and AI Engineer work from repository and locally observed evidence.

The split matters and is easy to get wrong in one direction. Reading the diff instead of the commit subject is local grounding and belongs here, binding everyone. Going outside for confirmation or comparison is external and belongs there, binding one role. A rule here that swept in the external half would tell QA to do the thing its charter forbids.

Tracked at coilyco-flight-deck/agent-compose#254.

Placement

Rewrite ### Front-load the context you know you need in place rather than appending a section. It is the same rule with a corrected trigger and an added stopping condition, and two adjacent sections saying similar things is how doctrine drifts.

Budget is not a constraint here. [tool.agentic-os.documentation-layout] allows 320 lines and 34000 chars. AGENTS.md is currently 226 lines and 23575 chars.

Dependency

agent-compose#254 removes this half from the roster. Until this lands, a bundle shipped to a seat without this base carries no version of the rule at all. Land this first, or land both together.

Done when

The section triggers on any consequential claim rather than on an edit.
It carries a stopping condition a reader can check against their own draft.
It states the thing-over-description rule, gap-as-task, the one-modality rule, and the bounds.
It stays clear of external validation, which is role-allocated elsewhere.
The rule is rewritten in place, with no second section covering the same ground.

## Problem The rule already exists and did not bind. `AGENTS.md:195` at `e7c8e559` reads: > ### Front-load the context you know you need > > Naming a gap is not closing it. When a convention, schema, or subsystem wiring is discoverable in the repo, a skill, or a doc, read it before planning. Before the first edit, list the conventions and subsystems the work touches and confirm you have read each one. > > A narrowed scope does not narrow the context budget. The **first** instance of a pattern needs the most grounding, because that first entry sets the schema everything after it copies. A single strats session on 2026-08-07 produced four failures this rule was supposed to prevent. All reversible, all caught, which is why they are usable material rather than an incident: * Wrote "information still needed: date, format, length, deadline" into two issues and stopped. Every fact was in an unread email. * Made campaign-level claims about two speaking engagements without measuring their audience. The numbers took four tool calls once attempted. * Concluded a profile "exists nowhere in the portfolio" after searching issues and repository metadata. It had been on `main` for two days. The tree was never read. * Named an issue and a PR the critical path for a dated commitment, from issue prose alone. The diff showed the branch reverted an architecture `main` had deliberately removed. The conclusion was not merely unsupported, it was backwards. The shared root: **an artifact describing a thing was accepted in place of the thing.** Issue text for code, commit subjects for diffs, metadata for contents. ## Why the existing rule did not bind Diagnosed in `coilyco-flight-deck/agent-compose#248`, and it resolves to both causes: 1. **The trigger is edit-shaped.** "Before the first edit" is a trigger a role writing an assessment, a ranking, or a verdict never reaches, so the rule reads as somebody else's. 2. **There is no stopping condition.** It says to read what you need and offers no test for whether you have. ## What this issue takes on `agent-compose` built a fixed version of this as role doctrine, then found that half of it is not role-scoped at all. That half belongs here, and lands with the two fixes intact: * The trigger becomes **any consequential claim**, not any edit. A claim is consequential when a reader could act on it or when it enters a durable artifact. * **Prefer the thing over a description of the thing.** Code over the issue describing it. The diff over the commit subject. File contents over metadata or a search hit. Raw responses over summaries. * **An identified gap is a task, not a disclaimer.** Recording that information is still needed and stopping is a failure whenever the information is reachable with the access already held. * **A stopping condition that can be checked.** Before delivering, every consequential claim either names the source that was opened, or is marked as inference with the observation that would settle it. Unavailability never silently promotes a guess into a fact. * **One modality is not proof of absence.** Searching issues establishes nothing about a repository tree, and a single empty query is not a negative result. * **Bounds.** Acquisition reaches only sources that would change a specific pending claim or decision. Curiosity is not a warrant. Cost scales with stakes. It grants no new authority, and sending, publishing, and destructive actions stay gated exactly as they are. ## Explicitly not in scope **Seeking validation from outside your own frame.** That behavior is role-allocated, not universal, and stays in agent-compose as a boundary held by the Executive Strategist. Six roles are chartered to stay inside the local frame: QA works to a fixed acceptance boundary, Designer works from Kai's supplied style, and Engineer, Ops, and AI Engineer work from repository and locally observed evidence. The split matters and is easy to get wrong in one direction. Reading the diff instead of the commit subject is **local** grounding and belongs here, binding everyone. Going outside for confirmation or comparison is **external** and belongs there, binding one role. A rule here that swept in the external half would tell QA to do the thing its charter forbids. Tracked at `coilyco-flight-deck/agent-compose#254`. ## Placement Rewrite `### Front-load the context you know you need` in place rather than appending a section. It is the same rule with a corrected trigger and an added stopping condition, and two adjacent sections saying similar things is how doctrine drifts. Budget is not a constraint here. `[tool.agentic-os.documentation-layout]` allows 320 lines and 34000 chars. `AGENTS.md` is currently 226 lines and 23575 chars. ## Dependency `agent-compose#254` removes this half from the roster. Until this lands, a bundle shipped to a seat without this base carries no version of the rule at all. Land this first, or land both together. ## Done when * The section triggers on any consequential claim rather than on an edit. * It carries a stopping condition a reader can check against their own draft. * It states the thing-over-description rule, gap-as-task, the one-modality rule, and the bounds. * It stays clear of external validation, which is role-allocated elsewhere. * The rule is rewritten in place, with no second section covering the same ground.

coilyco-ops referenced this issue

2026-08-09 04:02:19 +00:00

Agent-facing context assumes the operator is the principal, and the pronoun rule can leak onto strangers #979

coilyco-ops referenced this issue from a commit

2026-08-09 04:22:53 +00:00

docs(agents): trigger the front-load rule on any consequential claim

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-09 04:23:36 +00:00

docs(agents): claim-triggered front-load rule, and principal-scoped pronouns #980

coilyco-ops referenced this issue

2026-08-09 04:23:57 +00:00

Agent-facing context assumes the operator is the principal, and the pronoun rule can leak onto strangers #979