Development record
The brief gains a framing chapter under 01-product/ — the macro-why home: one section holds the project's framing, the why behind the why, and receives the brief-creation interview's committed framing products; the brief-lifeboat mapping gains the matching row so a lifeboat carries framing like any other section
Typed links: refines the brief skeleton's 01-product/ chapter (a new
section, not a rework of an existing one). Receives the committed framing
products of
itd-142;
only committed products land here — framing traces stay local per
adr-50,
as refined by adr-55: the construal as it presently stands is committed
record and readable by automated readers (the cold reading included); its
history is not.
Press Release
A brief now says why the why holds. The product chapter gains a framing section — the macro-why home: the frame the project reasons inside, stated where a reader can find it instead of reconstructed from scattered scope and context notes. It is a first-class brief section: the brief↔lifeboat mapping carries a matching row,
disembark probemeasures it against real repositories like any other section, and the brief-creation interview's committed framing products land in it with the same confirmation discipline as everything else in the brief.
Why This Matters
The brief records what the project is and what constrains it, but the frame
those answers were formed inside has no home: today it leaks into
02-context.md and 04-scope.md as asides, or stays in humans' heads. A
named framing section makes the macro-why a maintained artefact — and gives
the itd-142 interview a committed destination, so elicited framing lands in
the record rather than in a transcript that is discarded.
What's In Scope
- The new section under
01-product/(position and filename fixed at the planning interview), with its reading guide in the chapter README. - The matching row in the brief↔lifeboat mapping — a change to
internal/core/lifeboat/mapping.go, whose generated table and round-trip tests hold00-meta.mdin agreement. - The tier hypothesis for the new row (expected: blank at tier 0, partial at
best from conventions, grounded only abcd-native — like
product/personas, framing is a question for a human, not an extraction). - This repository's own framing section, written as the first instance.
- The construal statement the section opens with: what the situation is treated as, in one or two sentences — the surface a widening reading reads against; where it describes an intention rather than a commitment it carries the not-yet-real marker.
- The not-yet-real marker's form (ratified 2026-08-30): a blockquote line
holding exactly
**Status: NOT YET REAL.**, a blank line, then the statement as the first paragraph — the file-levelStatus: LIVEconvention carried to passage level. One exact token, reader-visible in the rendered prose, lintable later without new machinery. - Ruled (facilitator, 2026-08-28; decision log): the construal is sited as a brief section — this section — and adr-50 is extended to distinguish construal from revision history, the extension filed as an ADR in Iteration 1 before the construal surface is built (it files first in the build sequence; adr-55 is that extension). Ground: dropping the Step 2 reading would forfeit the position of greatest exposure; a glossary-only reading is a defensible fallback but must be stated as a bound, never passed off as the full reading.
- Construal revision passes the prior construal to the local ledger side rather than retaining it in the section — the brief holds the present (adr-5) and version control serves history; no in-section version trail.
What's Out of Scope
- The elicitation — itd-142 owns how framing is asked for; this intent owns where it lives.
- Framing traces — adr-50: only committed products enter the section.
- Glossary curation — the glossary README already names committed terms as the framing's machine-visible fingerprint; no new machinery here.
Acceptance Criteria
BDD format, per the itd-1 discipline. Initial set; refined at planning.
- Given the brief skeleton, when the section ships, then
01-product/contains the framing section, the chapter README indexes it, and00-meta.md's generated mapping table carries its row — with the round-trip test proving code and document agree. - Given a repository probed by
disembark probe, when coverage is reported, then the framing section is measured and reported with the same three-valued status as every other section. - Given an itd-142 interview that commits framing products, when they land, then they land in this section with confirmation provenance, and nothing uncommitted lands at all.
- Given the framing section, when it is read, then it opens with a one-or-two-sentence construal statement, and any passage describing an intention rather than a commitment carries the not-yet-real marker.
- Given a construal revision, when the section is rewritten, then the prior construal exists on the local ledger side and not in the brief.
- Given the framing section, when it is projected, then the construal statement and its load-bearing vocabulary are machine-extractable — fixed section heading, statement-first layout, the exact marker token — so the framing vocabulary can be pulled from the brief retrospectively (facilitator review requirement, 2026-08-28).
SOTA
Surveyed on 2026-10-23; sources, evidence tiers and the local fit risks are in the elicitation interviews SOTA note.
- Design-document convention keeps interpretation out of "context", which must be "entirely focused on objective background facts", and puts committed scope in goals and non-goals (Ubl, Design Docs at Google); a construal is interpretive, so it belongs beside goals, not in the context chapter.
- The problem is a single story ("a single specific story that shows why the status quo doesn't work", Shape Up ch. 6); the PR/FAQ writes it from the customer's point of view. Neither template marks built against intended.
- The one practitioner artefact with a structural line between exploring and committed is the opportunity solution tree (Torres): the outcome "sets the scope for discovery" and a backlog entry "is making a bet".
- Living-spec tools split the two by file, not by marker: OpenSpec keeps specs as
"how your system currently behaves" and changes in separate folders merged on
archive; Spec Kit bans speculation from a spec and confines open points to
[NEEDS CLARIFICATION: …]. RFC 2119 words cannot carry "intended, not built": they are for interoperation, used "sparingly". - The traceability pass of 2026-10-04 already recommends status in links, not
prose; the ratified
**Status: NOT YET REAL.**marker puts status in prose. The research disagrees with the ruling on that one point; the marker stands, recorded as the first instance of that status, to be superseded by section identifiers andrealiseslinks when that work lands. - A frame is a lens, not a solution (Dorst's frame creation, publisher description only; primary texts paywalled).
Path 2: the native section shaped to the design-doc convention, construal beside goals, the ratified marker kept, and a stable section identifier given at birth as the seam to link-carried status. No Go dependency.
The independent fit-challenge runs at plan time.
Open Questions
- Section position and filename within
01-product/(the chapter is numbered; inserting versus appending changes existing links). - Whether the tier hypothesis for framing matches personas (blank below abcd-native) once probed against the corpus — where they disagree, the mapping table loses.
- (SOTA 2026-10-23) Whether the framing section sits with the product chapter's goals and scope or opens the chapter; the design-doc convention argues against it reading as context.
- (SOTA 2026-10-23) Whether the section carries a stable identifier from its first instance, so the not-yet-real marker can later be replaced by links without a rewrite.
Evidence 2026-10-04 (a downstream lab)
Recorded for the product thinker; nothing here decides the question. A downstream private project's brief-authoring lab found that the present-tense-only convention makes a target-design brief read as a working product: 99 present-tense product claims against 9 "staged" markers. Its owner called this the biggest issue they face with abcd, and holds that the brief is the target design the product thinker owns. A framing chapter is one place a brief could say which of the two it is; the lab named this intent with itd-142 and itd-61.
Hypothesis 2026-10-04 (the brief's tense)
Recorded from the product thinker, 2026-10-04, answering how a brief describes what is not built yet, verbatim: "this is a big open question I'm currently testing on another repo. My current hypothesis: The brief is the main 'target design' document for the PT; while written in present tense, it's a vision of what the PT assumes the final product will look like. That way, the PT can 'think' about the product in a familiar way, while abcd helps them -- via the TF -- to make it a reality (step-by-step). We need SOTA research to ensure abcd will do that in a deterministic way, e.g. by listing implemented intents and/or plumbing implementations to each brief section; if the PT then changes the brief, abcd must assess whether a new intent/issue is required (and record it) or whether an existing intent (already filed, planned, and/or build) contradicts that change, in which case the PT is owed a design decision. Makes sense?" Recorded as a working hypothesis under test, not a ruling; a state-of-the-art pass on deterministic brief-to-record traceability was started the same day.
Audit Notes
Empty. Populated by intent-auditor when intent moves to shipped/.
Frontmatter
| id | itd-143 |
|---|---|
| type | intent |
| lifecycle | drafts |
| severity | minor |
.abcd/development/intents/drafts/itd-143-the-brief-gains-a-framing-chapter-under.md
open on GitHub ↗ · commit history ↗
Referenced by7
- adr-50Framing traces never enter the record, and automated reviewers never read themrelated
- adr-55The construal stands in the record; its history does notrelated
- adr-2609021016288378A reframe occasioned by a reading is a committed pointer to an event whose content stays local, and the frame it fingerprints is the framing as it presently stands, which adr-55 enumerates as three committed surfacesrelated
- iss-2610262031376538itd-143 leaves the framing section's position and filename to its planning interview, while the product chapter already lists 06-framing.mdrelated
- iss-2610262034068157draft itd-143 says the brief gains a framing chapter whose position and filename are still to be fixed; the capture surface's reframe reads that chapter's Construal section as a committed surface at a fixed pathrelated
- iss-2610262040511595The construal glossary describes the brief's framing chapter as existing with a construal; itd-143, still a draft, has that chapter and its first instance still to be written.related
- iss-2610262042329594The glossary forbids calling a reading's position a step; itd-143 calls the widening reading the Step 2 readingrelated
mentions13
- adr-5Brief is the current state; no version label, no archive directory
- dcn-26082200000000072026-08-22 — Interview-workstream records filed (the 2026-08-22 handover's
- dcn-26083000000000072026-08-30 — Framing section sited as `01-product/06-framing.md`, appended rather than inserted so existing chapter links hold (facilitator). The brief↔lifeboat mapping row and the `00-meta.md` regeneration are deferred to itd-143's build, carried from session 1: the filing PR carries no code beyond the lapse enum line.
- dcn-26083000000000102026-08-30 — The brief-lifeboat mapping row for the framing section lands in the Phase 1 filing after all (orchestrator's improvisation, logged for the facilitator): `TestEveryBriefSectionHasARow` refuses a brief section without a row, an armed test cannot stay red, and the construal must file first; the row is its own commit, droppable if the facilitator prefers to hold it for itd-143's build. This supersedes the deferral recorded above.
- dcn-26083000000000112026-08-30 — Phase 1 adversarial review (ruthless-reviewer, fresh context) findings captured as iss-2608300114352100 (a first name disclosed through a homonym in the session-1 lapse record; the wording is replaced, and the pushed branch's history still carries it until the PR is squash-merged), iss-2608300114357633 (this log contradicting the branch, remedied by the two lines above), and iss-2608300114359543 (record consistency: one role name for the 2026-08-28 rulings, the ratified marker form in itd-143, the framing section statement-first, no adoption-date marker on invariant 15, the phase count, and "Phase 2 planning" reworded so it cannot read as roadmap Phase 2). All three resolved in the same change.
- dcn-26100400000000062026-10-04 (the product thinker, working hypothesis, not a ruling): a brief is the product thinker's target design, written in present tense as the vision of the finished product; abcd makes it real step by step through the technical facilitator, deterministically: each brief section lists the intents and implementations that realise it, and a brief change is assessed for a new intent or issue, or for a contradiction with a filed, planned or built intent, which owes the product thinker a design decision. Under test on another repository; a state-of-the-art pass follows. Recorded on itd-61, itd-142 and itd-143.
- iss-2608300114357633The decision log's last word on two questions is the opposite of what the filing branch does: it defers the brief-lifeboat mapping row to itd-143's build while the branch adds the row, and it records the roadmap phase home as deferred while the branch authors Phase 7 on a facilitator ruling that the log never records. Append-only, so the remedy is appended lines carrying both rulings.
- iss-2608300114359543Record consistency findings from the Phase 1 adversarial review: itd-142 and itd-143 attribute the 2026-08-28 rulings to a third role name; itd-143 still describes the not-yet-real marker as pending in a form the same filing ratifies differently; 06-framing.md places a dated preface between the Construal heading and the token, so the section is not statement-first as its own rule and itd-143's projection criterion require; invariant 15 carries an adoption-date marker no sibling carries; 04-scope.md line 24 still counts seven phase docs; Phase 7 and the log say 'Phase 2 planning' where roadmap Phase 2 is a shipped phase; the phases README says phases 1-6 are organised by capability moment; the lifeboat mapping comment counts 23 rows.
- iss-2610262031278962The framing chapter already exists under 01-product/; 03-out-of-scope lists itd-143, which promises that chapter, as work not yet under way.
- itd-1Every Intent Has Acceptance Criteria; Every Audit Verifies Them
- itd-61A Human Edit To The Brief Cannot Commit Until Its Implied Intents And Principles Are Drawn Out And Reconciled
- itd-142The brief-creation interview: abcd elicits a repository's brief in a staged conversation — narrative first, then frontier rounds that ask only what the record cannot yet settle, options at conjectural questions (at most three candidate construals, a ceiling not a target, with a null answer always available), and a per-item confirmation — distilling committed products into the brief and a ledger while the transcript is discarded. Entry is one door for both modes: a brownfield repository arrives pre-populated from embark probe coverage, provenance-stamped and still requiring confirmation; a greenfield repository is the same interview run from the all-blank coverage state. Command-shaped, because it mutates state — abcd ships zero skills
- itd-2610040817105016Every brief section shows what realises it, and a brief change names what it touches