Skip to content

docs(architecture): bring chapter 11 to the chapter style #2419

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
braboj merged 3 commits into from
Oct 30, 2026
Merged

docs(architecture): bring chapter 11 to the chapter style #2419

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e20b783
docs(architecture): bring chapter 11 to the chapter style
braboj Oct 30, 2026
7a60bb7
docs(architecture): drop the stale core score claim from chapter 11
braboj Oct 30, 2026
eab2811
docs(architecture): remove chapter 11.3
braboj Oct 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 23 additions & 26 deletions docs/architecture/11-risks-and-technical-debt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,30 @@
# 11. Risks and technical debt

The risks below could make the templates cost a project more than they
return, even when the system works as designed. Each mitigation in place
rests on a requirement or a decision where one exists, and a risk with no
mitigation shows a dash.

## 11.1 Risks

| # | Risk | What it looks like | Mitigation in place |
|---|------|--------------------|---------------------|
| R01 | Attention dilution | Relevant rules are buried even when the window holds the chain | Context tiers (SYS-16); the template-quality ratchet |
| R02 | Literalism | Hundreds of MUSTs drive overengineering or irrelevant work | Rule language reserves MUST for what matters; the scorer flags long rules |
| R03 | False confidence | Green structural checks read as evidence that agents do better | Chapter 10 keeps effectiveness separate; the benchmark measures it |
| R04 | Recursive governance | Rules about checks, audits and releases create more surfaces than they retire | A decision record is owed only for the composition model |
| R05 | Backlog exhaustion | The tracker becomes an inventory, not a set of commitments | Intake dispositions; only a milestone means scheduled |
| R06 | Product displacement | Keeping policy consistent takes the time meant for adopters | — |
| R07 | Supply chain | Remote policy changes behaviour without review | Consumers pin a fork version and adopt changes deliberately |
| R08 | Overcompression | A shorter file drops load-bearing policy | Compression is judged on agent outcomes, not bytes |
| R09 | Lost downstream learning | Consumer observations are discarded instead of weighed | Issue forms ask for the outcome and evidence |
| # | Risk | What it looks like | Mitigation in place | Source |
|---|------|--------------------|---------------------|--------|
| R01 | Attention dilution | Relevant rules are buried even when the window holds the chain | Context tiers (SYS-16); the template-quality ratchet | QG-02-02, QG-04-02 |
| R02 | Literalism | Hundreds of MUSTs drive overengineering or irrelevant work | Rule language reserves MUST for what matters; the scorer flags long rules | FR-01-01, QG-04-02 |
| R03 | False confidence | Green structural checks read as evidence that agents do better | Chapter 10 keeps effectiveness separate; the benchmark measures it | QG-01-02 |
| R04 | Recursive governance | Rules about checks, audits and releases create more surfaces than they retire | A decision record is owed only for the composition model | - |
| R05 | Backlog exhaustion | The tracker becomes an inventory, not a set of commitments | Intake dispositions; only a milestone means scheduled | ADR-024 |
| R06 | Product displacement | Keeping policy consistent takes the time meant for adopters | - | - |
| R07 | Supply chain | Remote policy changes behaviour without review | A project pins a released tag of upstream or a fork, and moving the pin changes no context file | FR-08-04, FR-09-03 |
| R08 | Overcompression | A shorter file drops load-bearing policy | Compression is judged on agent outcomes, not bytes | QG-02-02 |
| R09 | Lost downstream learning | Consumer observations are discarded instead of weighed | Issue forms ask for the outcome and evidence | - |

## 11.2 Technical debt

| Area | Debt |
|------|------|
| Policy | Oversized high-reach templates; too many absolute rules; local incidents generalised globally; procedures mixed into persistent policy. The five lowest-scoring `core/` files are #2024 |
| Composition | File paths act as identity; merging and conflict handling depend on the agent, not a tool |
| Validation | Extensive structural checks, thin evidence that agents follow the rules |
| Documentation | Large audit and journal surfaces; ADR density out of proportion to product capability |
| Product | No installed generator, no stable project configuration, no upgrade or diff workflow; the declaration block is a target (ADR-053) |

## 11.3 What the evidence does not cover

The benchmark has run one web application, built in one session, by
strong and weak models. Thin specifications, cheaper models and many
sessions over months are only partly tested, and no round has compared a
reference-only file with a hybrid one. Rounds and their limits are in
`docs/audits/`.
| Area | Debt | Source |
|------|------|--------|
| Policy | Oversized high-reach templates; too many absolute rules; local incidents generalised globally; procedures mixed into persistent policy | QG-04-02 |
| Composition | File paths act as identity. An agent writing an inline or hybrid file applies overrides and settles conflicts itself; only the emitter, still proposed, does it in a tool | ADR-058, proposed |
| Validation | Extensive structural checks, thin evidence that agents follow the rules | QG-01-02 |
| Documentation | Large audit and journal surfaces; decision records out of proportion to product capability | - |
| Product | The emitter runs from a clone of the templates; no stable project configuration exists, and no tool shows what a release changes in a project's files. The declaration block is a target | ADR-053, ADR-058, proposed |
Loading