Generated from
cat-harness/skills/sdlc/sdlc-core/where-a-proposal-goes.md— do not edit here.
Where a proposal goes — the issue, not the documentation
A design proposal is a comment on the issue it is for. Not a page in
docs/. Owner, 2026-09-19:
bad habit, do not do… put feature developemnt/etc proposals in the doucmentaiton. the should be attached as comment to appporiate issues (for now tooling is github) or in discussion chat. do not pollute the KG with SDLC churn.
The habit this corrects, with the evidence
Measured 2026-09-19: docs/folio-assistant/proposals/ held four files.
One of them, deployment-topologies.md, was written and merged that same day
by the session that then added a further section to it an hour later — so
this was a live habit producing new churn, not old debt being tidied.
All four moved to fsh-guts/. That broke their published URLs, including
links in issues #363 and #223 and a comment posted an hour earlier pointing at
deployment-topologies.html. The breakage is the cost of the habit, paid
once; it is written here so the next agent does not have to pay it again to
learn the rule.
Why it is wrong beyond taste
The rendered site is the folio’s published output and the knowledge graph is what tools read. A design proposal is neither:
- it is an argument about what to build, superseded the moment it is decided
- its audience is one or two people, for about a week
- as a page it gets a permanent URL, so it is cited long after it stopped being true
- it goes through translation, QA sidecars and link auditing — all of which cost something, and none of which it needs
An issue comment has the right lifetime, the right audience and the right tooling, and it sits next to the decision it produced.
The test
Would somebody who does not work on this platform want to read it?
If no, it is not documentation. A folio’s reader wants to know what the content says and how to work with it; they do not want to know which of four options the platform chose for its work-plan store.
Where each thing goes
| what | where |
|---|---|
| a design proposal, an options analysis, an impact assessment | a comment on the issue |
| a decision worth citing later | the issue, and one or two lines in the skill the decision governs |
| structured content worth keeping but not publishing | fsh-guts/ — see fsh-guts |
| how an agent should behave | a skill, per AGENTS.md’s own banner |
| what a reader of the folio needs | docs/ |
The exception, stated so the rule survives contact
Not everything in a proposal is churn. The reasoning that survives a decision is often the most valuable thing written that week, and pretending otherwise gets the rule ignored the first time it is inconvenient.
The line: the argument is churn and belongs on the issue; the rule that
came out of it is durable and belongs in the skill it governs, in a
paragraph, with the evidence that established it. This repository already
does that well — AGENTS.md and the folio-core skills are full of “this was
measured on this date and here is what it cost”, and none of that is a
proposal document.
So the move is not “delete the thinking”. It is: put the conclusion where it
is enforced, put the argument where it is discussed, and keep the long form in
fsh-guts/ if it is worth keeping at all.
Related
fsh-guts— the destination, and the never-delete ruleAGENTS.md§”🛑 Do not edit this file to change how agents work” — the same argument one level up: a rule with no skill is a rule with no home