docs(enablement): ticket descriptions survive a refactor, not re-derivation#218
Conversation
…vation Roll back the 'description should let a future agent work without re-derivation' principle. It pushed toward dumping codebase context into tickets, which drives verbosity and staleness: the snapshot ages the instant the code moves, and a stale line in context reads as a confident truth the next agent steers by. The corrected governing test: a description survives a refactor of the code it concerns. It owns the what and the why; it leaves the how to the agent holding the code. Grounded in how attention actually reads — every token competes for a finite budget, salience anchors over retrieval, and repetition is weighting. So repeat the durable (intent) and never mirror the mutable (code): one-source-of-truth reinforced, not duplicated.
brandon-fryslie
left a comment
There was a problem hiding this comment.
Adversarial review
A docs-only reframe of ticket-description guidance in three passages. The core argument — that descriptions should carry intent rather than codebase snapshots — is internally sound, and the 'enough to act without guessing' language in Ingredient 1 (line 36) preserves a completeness floor for the creation-section bullets. One genuine narrowing: the well-tended-system criterion at line 226 replaces an agent-outcome signal ('re-derivation is rare') with a description-property signal ('stays accurate across refactors'). These are different observables, and the substitution creates a blind spot for descriptions that are refactor-proof but underspecified.
…tem criterion
The success-criteria bullet rewrite kept 'survives a refactor' but dropped
'enough to act', so it would accept refactor-proof but underspecified
descriptions ('improve the auth module'). Both signals belong: a description
must carry what+why (scope, constraints, success) AND avoid encoding the
implementation. Restated using the governing test's own phrase ('enough to
act without guessing') so the criterion reinforces the durable formula rather
than minting a second wording that could drift from it.
brandon-fryslie
left a comment
There was a problem hiding this comment.
Adversarial review
Docs-only PR reframing one principle across three passages. The intent is coherent and well-argued. The new text is internally consistent and the three changed sites all move in the same direction. No logic errors, no contract breaks, no code touched. One minor representation drift found.
The first creation-checklist bullet restated the thesis of the paragraph immediately above it — adjacent redundancy, not instrument-repetition. The section's own principle draws exactly this line: repetition bears when it reinforces at distance (the end-of-doc success criterion), and dilutes when it shadows the strong prose form one line later. The bold governing test leads the section as its thesis; the surviving bullets are all additive, and 'names concepts not file:line' already carries the not-a-snapshot mechanism.
brandon-fryslie
left a comment
There was a problem hiding this comment.
Adversarial review
Docs-only change; the three-paragraph rewrite of the ticket-creation section is internally coherent and the refactor-survival principle is logically sound. The Ingredient 1 rewrite and success-criterion bullet align cleanly with the new principle, and the two resolved threads are correctly absent. One minor representation drift at line 82: the appended clause designates concept-naming as 'the concrete mechanism behind surviving a refactor,' but the principle as defined in the three preceding paragraphs is broader than reference stability alone.
…, not the
The clause asserted via the definite article that naming concepts over
file:line references is THE mechanism behind surviving a refactor. It is one
dimension (reference stability); a concept-named bullet can still encode how
('refactor the singleton out of the cache layer') and fail the test. 'One
concrete way descriptions survive a refactor' keeps the link to the principle
without claiming to be the whole of it.
brandon-fryslie
left a comment
There was a problem hiding this comment.
Adversarial review
Docs-only rewrite of three passages in design-docs/preparing-the-next-loop.md. The prose argument is internally consistent, the three new paragraphs cohere with the remaining bullets and with the success-criteria rewrite at line 225, and the prior three review threads are correctly addressed in the diff. No logic errors, no contradictions with unchanged document sections, and no new rules are introduced without documentation in the PR description.
Rolls back the ticket-description principle in `design-docs/preparing-the-next-loop.md`.
What changed
The old guidance — "the description is enough that an agent can work it without re-deriving the context that motivated the ticket" — pushed toward dumping codebase context into tickets. That drives two failures:
The corrected principle
A description survives a refactor of the code it concerns. It owns the what and the why; it leaves the how to the agent holding the code.
Grounded in how LLM attention actually reads: every token competes for a finite budget, salience anchors over retrieval, and repetition is weighting. So repeat the durable (intent), never mirror the mutable (code) —
[LAW:one-source-of-truth]reinforced, not duplicated. The refactor test is[LAW:behavior-not-structure]in prose: a sentence a refactor can falsify was asserting how; one it leaves standing was asserting what.Scope
Three passages reframed (Ingredient 1, the ticket-creation section, the success criteria). Three other "re-derive" mentions left intact — they describe re-derivation caused by staleness/neglect, which the corrected principle prevents rather than endorses.
Docs-only; no code or runtime template carries the old framing.