writing contract: one action per sentence, constraint before the action it limits, preloaded into every agent #69

New issue

Open

opened 2026-07-28 17:41:30 +00:00 by crenshawdev · 1 comment

crenshawdev commented

2026-07-28 17:41:30 +00:00

(Migrated from github.com)

What you want Cadence to do

Two writing rules, delivered as one contract skill preloaded into every agent via the skills: frontmatter field.

Rule 1, one action per sentence. Do not use a participle to chain actions. The planner's own example in <task_anatomy> demonstrates the problem it causes:

Add POST /login validating {email,password} against User via bcrypt, returning a 15-min JWT cookie

One sentence, three obligations, two participles carrying the structure. The executor reads that as its instruction. Rewritten:

Add POST /login. Validate {email,password} against User via bcrypt. Return a 15-minute JWT cookie.

The rule is narrower than it sounds. "validating", "returning", "checking, then removing" hide sequence and dependency. Gerunds used as plain nouns ("planning", "testing") are fine, and a blanket -ing ban costs more in awkwardness than it returns.

Testable form: if a sentence contains more than one thing the reader must do, split it.

Rule 2, placement. State the constraint before the action it limits, and the outcome before the detail supporting it.

Two applications. The planner is told each Action should include "what to avoid with WHY" but not where that goes; at the end of a long Action the executor has already formed intent before it reaches the prohibition. And completion reports are ordered by production sequence (plans executed, commits, deviations, open items, goal-check verdict) with the verdict last, when the verdict is the thing anyone actually wants.

Scope is deliberately narrow. Verify fields and the finding schema already comply. The real targets are Action fields, checkpoint bodies, and anywhere prose carries more than one obligation.

These are derived from ASD-STE100 concepts. The controlled dictionary is explicitly out of scope: it is copyrighted, it is what makes STE output read as stilted, and a dev tool has a different vocabulary than an aircraft manual. Do not claim STE compliance. No linter and no external dependency; this is prompt-side only.

Why the default no is wrong here

This proposal has to clear a bar the others do not, and it should be argued honestly rather than assumed.

The counter-argument first. Anthropic removed over 80% of Claude Code's system prompt for Claude 5 models with no measurable loss on their coding evaluations, and the stated shift is from restrictive rules to judgment: "write code that reads like the surrounding code" in place of "never write multi-paragraph docstrings." This proposal adds mechanical prompt rules at the moment the vendor's own measured result says to delete them. Six of the other items in this milestone subtract. This one adds, and it is the only one that does.

Why it survives anyway. The blog's finding is about guidance the model can derive from context. Comment density is derivable: the surrounding code shows it. The shape of a PLAN.md Action field is not, because there is no surrounding corpus to match. The executor sees one Action field written by one planner, and nothing tells it whether a three-obligation sentence was one task or three.

The judgment-framed version is available and should probably be preferred where it works: "write the Action so the executor can act on one step at a time" carries the intent without the mechanics. Whoever implements this should try the judgment form first and fall back to the participle rule only if plans keep arriving with bundled obligations.

Rule 2 is the stronger half and should survive even if rule 1 does not. Outcome-first is where three independent lines converge: STE's warnings-before-steps placement rule, ADHD-oriented formatting practice, and the Opus 5 guide's explicit instruction that the first sentence should answer "what happened." Three sources arriving at the same rule from different directions is better evidence than any of them alone.

What the current surface cannot earn: an Action field whose obligations are countable. Today an executor's task boundaries depend on how the planner happened to punctuate.

What it costs

Resident context in every agent. The contract skill is preloaded, so its full content sits in each agent's startup context. Keep it short; if it grows past a screen it has failed.

A rule that is followed approximately. Prompt-side rules degrade gracefully here, which is the honest reason to accept them. A bundled sentence or a misplaced constraint costs readability, not correctness. That asymmetry is exactly why the terminology half of this analysis is filed separately as a schema change rather than a writing rule: that one fails silently, and this one does not.

A new file per agent frontmatter. Shared with the effort-as-rigor-lever proposal, which needs the same skills: preload mechanism. If both land, this adds no new machinery. If this lands alone, it introduces the mechanism by itself and should say so.

The silent-skip failure. A skills: entry that names a missing or disabled skill is skipped with only a debug-log warning, so a typo yields an agent running without the contract. Needs a self-verify CONTRACTS entry that asserts the skill resolves.

The measurement. Count multi-obligation sentences in Action fields before and after, and count executor deviations attributable to a misread task boundary. The second number is the one that matters and Cadence does not currently record it in a countable form. Say so.

Why this belongs in `main` and not a fork

Cadence writes the artifacts. A user does not author PLAN.md; the planner does, and the executor reads what the planner wrote. The handoff between two Cadence agents is entirely inside Cadence's surface, so the quality of that prose is Cadence's to own, not a preference a user could reasonably fork over.

The orchestrator half of this analysis deliberately does not ship here. Narration style belongs to the user's own session, which Cadence cannot configure, and it belongs in a user's CLAUDE.md instead. Keeping that out is part of the proposal: this covers only the artifacts Cadence itself produces.

The terminology half of the same analysis is filed separately as an identity/ID schema change, because a prose rule that fails silently is the wrong tool for a drift that breaks merges.
The conventions.md reach bug gates any orchestrator-side rule. This proposal does not add one, deliberately.

## What you want Cadence to do Two writing rules, delivered as one contract skill preloaded into every agent via the `skills:` frontmatter field. **Rule 1, one action per sentence.** Do not use a participle to chain actions. The planner's own example in `<task_anatomy>` demonstrates the problem it causes: > Add POST /login validating {email,password} against User via bcrypt, returning a 15-min JWT cookie One sentence, three obligations, two participles carrying the structure. The executor reads that as its instruction. Rewritten: > Add POST /login. Validate {email,password} against User via bcrypt. Return a 15-minute JWT cookie. The rule is narrower than it sounds. "validating", "returning", "checking, then removing" hide sequence and dependency. Gerunds used as plain nouns ("planning", "testing") are fine, and a blanket `-ing` ban costs more in awkwardness than it returns. Testable form: if a sentence contains more than one thing the reader must do, split it. **Rule 2, placement.** State the constraint before the action it limits, and the outcome before the detail supporting it. Two applications. The planner is told each `Action` should include "what to avoid with WHY" but not where that goes; at the end of a long Action the executor has already formed intent before it reaches the prohibition. And completion reports are ordered by production sequence (plans executed, commits, deviations, open items, goal-check verdict) with the verdict last, when the verdict is the thing anyone actually wants. Scope is deliberately narrow. `Verify` fields and the finding schema already comply. The real targets are `Action` fields, checkpoint bodies, and anywhere prose carries more than one obligation. These are derived from ASD-STE100 concepts. The controlled dictionary is explicitly out of scope: it is copyrighted, it is what makes STE output read as stilted, and a dev tool has a different vocabulary than an aircraft manual. Do not claim STE compliance. No linter and no external dependency; this is prompt-side only. ## Why the default no is wrong here This proposal has to clear a bar the others do not, and it should be argued honestly rather than assumed. **The counter-argument first.** Anthropic removed over 80% of Claude Code's system prompt for Claude 5 models with no measurable loss on their coding evaluations, and the stated shift is [from restrictive rules to judgment](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models): "write code that reads like the surrounding code" in place of "never write multi-paragraph docstrings." This proposal adds mechanical prompt rules at the moment the vendor's own measured result says to delete them. Six of the other items in this milestone subtract. This one adds, and it is the only one that does. **Why it survives anyway.** The blog's finding is about guidance the model can derive from context. Comment density is derivable: the surrounding code shows it. The shape of a `PLAN.md` Action field is not, because there is no surrounding corpus to match. The executor sees one Action field written by one planner, and nothing tells it whether a three-obligation sentence was one task or three. The judgment-framed version is available and should probably be preferred where it works: "write the Action so the executor can act on one step at a time" carries the intent without the mechanics. Whoever implements this should try the judgment form first and fall back to the participle rule only if plans keep arriving with bundled obligations. **Rule 2 is the stronger half and should survive even if rule 1 does not.** Outcome-first is where three independent lines converge: STE's warnings-before-steps placement rule, ADHD-oriented formatting practice, and the Opus 5 guide's explicit instruction that the first sentence should answer "what happened." Three sources arriving at the same rule from different directions is better evidence than any of them alone. What the current surface cannot earn: an `Action` field whose obligations are countable. Today an executor's task boundaries depend on how the planner happened to punctuate. ## What it costs **Resident context in every agent.** The contract skill is preloaded, so its full content sits in each agent's startup context. Keep it short; if it grows past a screen it has failed. **A rule that is followed approximately.** Prompt-side rules degrade gracefully here, which is the honest reason to accept them. A bundled sentence or a misplaced constraint costs readability, not correctness. That asymmetry is exactly why the terminology half of this analysis is filed separately as a schema change rather than a writing rule: that one fails silently, and this one does not. **A new file per agent frontmatter.** Shared with the effort-as-rigor-lever proposal, which needs the same `skills:` preload mechanism. If both land, this adds no new machinery. If this lands alone, it introduces the mechanism by itself and should say so. **The silent-skip failure.** A `skills:` entry that names a missing or disabled skill is skipped with only a debug-log warning, so a typo yields an agent running without the contract. Needs a self-verify CONTRACTS entry that asserts the skill resolves. **The measurement.** Count multi-obligation sentences in `Action` fields before and after, and count executor deviations attributable to a misread task boundary. The second number is the one that matters and Cadence does not currently record it in a countable form. Say so. ## Why this belongs in `main` and not a fork Cadence writes the artifacts. A user does not author `PLAN.md`; the planner does, and the executor reads what the planner wrote. The handoff between two Cadence agents is entirely inside Cadence's surface, so the quality of that prose is Cadence's to own, not a preference a user could reasonably fork over. The orchestrator half of this analysis deliberately does not ship here. Narration style belongs to the user's own session, which Cadence cannot configure, and it belongs in a user's CLAUDE.md instead. Keeping that out is part of the proposal: this covers only the artifacts Cadence itself produces. ## Related - The terminology half of the same analysis is filed separately as an identity/ID schema change, because a prose rule that fails silently is the wrong tool for a drift that breaks merges. - The `conventions.md` reach bug gates any orchestrator-side rule. This proposal does not add one, deliberately.

crenshawdev commented

2026-07-28 17:41:50 +00:00

(Migrated from github.com)

Cross-links:

#70 is the other half of the same analysis. That half is a schema change rather than a writing rule, because the drift it addresses fails silently and this one degrades gracefully.
#67 gates any orchestrator-side rule. This proposal deliberately adds none, so it is not blocked, but a future rule in conventions.md inherits whatever reach that file actually has.
#63 needs the same skills: preload mechanism.

Cross-links: - #70 is the other half of the same analysis. That half is a schema change rather than a writing rule, because the drift it addresses fails silently and this one degrades gracefully. - #67 gates any orchestrator-side rule. This proposal deliberately adds none, so it is not blocked, but a future rule in `conventions.md` inherits whatever reach that file actually has. - #63 needs the same `skills:` preload mechanism.