reinforce-design-constraints

What this skill does

An agent acts only on what is in its context. `CLAUDE.md` is the **one** doc Claude Code auto-loads into every agent before it does anything — so it is the only place a constraint is guaranteed to be seen at the moment an agent would otherwise violate it. A crucial design constraint that lives only in an ADR, a code comment, a linked knowledge doc, or someone's head is **invisible** to the agent who needs it: agents can't know what isn't in their system prompt, and they don't follow links they don't know exist.

This skill traverses the knowledge graph, finds the crucial design constraints, and makes sure each one is stated **inline** in `CLAUDE.md` — concisely, with a **link** to its full rationale so an agent who wants the whole story can discover it. The binding rule is in front of every agent; the derivation stays one hop away.

<what-counts>
A **design constraint** is a load-bearing rule about how the system must be built or changed. It passes all three tests:
1. **Load-bearing** — it shapes how code/architecture must be written, not just what exists.
2. **Violation causes harm** — breaking it causes breakage, silent data loss, rework, or a security/correctness hole. (If nothing bad happens when it's ignored, it's a preference, not a constraint.)
3. **Non-obvious from the code** — a competent agent reading the relevant files would not infer it. (If the code makes it self-evident, it doesn't need hoisting.)

They come in a few shapes:
- **Invariants** — "every hook output string must stay under 10k chars or Claude Code silently truncates it and drops the tail."
- **Prohibitions** — "never clobber existing `CLAUDE.md` content; append and link."
- **Required patterns** — "build the operator seam test-first; never build one speculatively."
- **Boundaries** — "the brief carries decisions, not mechanics."

**Not constraints** (leave them in the graph or out entirely): general orientation ("auth lives in `src/auth`"), style preferences, anything obvious from the code, transient task state, and the promode methodology itself (that's hook-delivered and never goes in `CLAUDE.md`).
</what-counts>

<the-tension>
`CLAUDE.md` enters *every* agent's context, so every inline line is a token tax paid on every run that also dilutes attention. So this is **not** "inline everything." Only constraints that pass the three tests earn an inline spot; their full rationale, edge cases, and derivation stay in a linked doc. The decision rule is **criticality, not topic** — exactly the inline-vs-linked discipline in the `agent-knowledge-wiki` reference (under the `promode-audit` skill). Keep `CLAUDE.md` a lean launchpad; a constraint section that balloons is itself a finding.
</the-tension>

<process>
1. **Traverse the graph.** Start at `CLAUDE.md` and follow its links outward through the knowledge docs (ADRs/decision nodes, runbooks, subsystem docs). Then sweep beyond the graph for constraints that were never captured: grep code/config for landmine markers (`DO NOT`, `must`, `never`, `WARNING`, `HACK`, load-bearing magic numbers), and fold in anything learned this session or named by the user.
2. **Extract candidates.** For each rule you find, write it as one imperative sentence plus its *why*. Run the three tests in `<what-counts>`. Drop anything that fails.
3. **Recover the why.** A constraint must trace to a real rationale. If the why exists in a doc, note the link. If it's folklore with no recoverable reason, **surface it, don't enshrine it** — an unexplained "never do X" is as likely a cargo-cult rule as a real one; ask before promoting it, and capture the why as a node once confirmed (grounded, because it was learned by doing).
4. **Check coverage.** For each surviving constraint, ask two questions of the current `CLAUDE.md`: (a) Is the rule stated inline? (b) Is there a link to its full rationale? Note which are missing, only-linked (invisible), or only-inline (no path to expand).
5. **Reinforce.** Edit `CLAUDE.md` so each crucial constraint is inline in the format below, with a signpost link. If the rationale doc doesn't exist yet, create it as a node and link it into the graph. **Never clobber** — integrate into the existing structure; append and link. If there's no `CLAUDE.md`, create a minimal one as the root.
6. **Report.** List what you hoisted inline, what links you added, any rationale nodes you created, and any candidate constraints you deliberately left in the graph (with why) so the inline core stays lean.
</process>

<inline-format>
Each crucial constraint is one tight bullet: the rule as an imperative, a one-line why, and a link to expand. Group them under a clear heading (e.g. `## Design constraints` or `## Hard constraints`) so an agent finds them fast.

```markdown
## Design constraints
- **Hook output strings must stay under 10k chars.** Claude Code silently truncates longer output to a preview and drops the tail — split at section boundaries instead. See [hook delivery](docs/main-agent-delivery.md).
- **Never put methodology in the project's `CLAUDE.md`.** It's the project's own file and the knowledge-graph root; the brief is hook-delivered. See [why](docs/main-agent-delivery.md).
```

The statement is inline so no agent misses it; the link carries the full rationale and edge cases for **expanded discovery**. State the rule in exactly one inline home and let the linked doc hold the rest — *one idea, one home*, with the headline as its earned inline exception.
</inline-format>

<guardrails>
- **Don't bloat the launchpad.** Inline the rule, not the essay. If you're tempted to inline more than ~2 lines per constraint, that surplus belongs in the linked doc.
- **Never clobber `CLAUDE.md`.** Append and integrate; preserve everything already there.
- **The project's `CLAUDE.md` is the project's own file.** Don't import promode's methodology into it — that's the hook's job.
- **Every constraint links somewhere expandable.** Inline-only with no path to the full story half-fails the skill's purpose; only-linked with no inline rule fully fails it.
- **Keep it grounded.** No speculative constraints — only rules with a real, traceable why.
</guardrails>

<success_criteria>
- Every crucial design constraint in the repo is stated inline in `CLAUDE.md`, concisely, with a link to its full rationale.
- No agent editing an affected area could plausibly miss the rule, and any agent wanting the reasoning can reach it in one hop.
- `CLAUDE.md` stayed a lean launchpad — only constraints that pass the three tests went inline; the rest stayed linked.
- Existing `CLAUDE.md` content is intact; nothing was clobbered.
</success_criteria>

<related>
- **`promode-audit`** finds these gaps read-only (its Agent-knowledge dimension / CLAUDE.md health check); this skill is the **write action** that fixes one class of finding it surfaces.
- **`agent-knowledge-wiki`** reference (under `promode-audit`) — the inline-vs-linked, criticality-not-topic rules this skill applies.
- **`managing-agent-knowledge`** — for a heavyweight, source-backed corpus when the graph outgrows the lightweight default.
</related>