reinforce-design-constraints

name

reinforce-design-constraints

description

Walk the knowledge graph (rooted at CLAUDE.md) and ensure every crucial design constraint — invariants, prohibitions, required patterns, load-bearing decisions — is guaranteed-loaded into the nearest loaded CLAUDE.md orientation that governs the affected area: stated inline, or @import-transcluded when it must stay in its own file, with a link to its full rationale for expanded discovery. Use when constraints are buried in ADRs, knowledge docs, code comments, or tribal knowledge; when an agent violated a rule it had no way to know; or when asked to surface, hoist, lift, strengthen, or reinforce design constraints, or make them discoverable to agents.

An agent acts only on what is in its context. CLAUDE.md files are the loaded project orientation: the root covers the repo, and major subdirectories may have their own CLAUDE.md for local rules. 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 guaranteed-loaded into the nearest loaded orientation file that governs the affected area — stated inline (concisely), or @import-transcluded from that CLAUDE.md when the rule is too long to inline cleanly or lives in a shared doc — 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 the affected agent (a plain link is not — the agent may never open it); the derivation stays one hop away.

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).

Loaded orientation enters agent context, so every inline line is a token tax 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. When even the *concise* rule is too long to inline cleanly, or it's a shared critical doc, **`@import` it** from the governing `CLAUDE.md` instead — transclusion guarantees its content loads (unlike a plain link) without inlining the essay. The decision rule is **criticality, not topic** — exactly the guaranteed-load discipline in the `agent-knowledge-wiki` reference (under the `promode-audit` skill). Keep each `CLAUDE.md` a lean launchpad; a constraint section that balloons is itself a finding, and may mean local rules should move to subtree orientation. 1. **Traverse the graph and map orientation.** Start at the root `CLAUDE.md` and follow its links outward through the knowledge docs (ADRs/decision nodes, runbooks, subsystem docs). Detect existing `CLAUDE.md` files along relevant paths so you know which loaded orientation governs each area. 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 ``. 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. **Choose placement.** Repo-wide or cross-cutting rules go in the root `CLAUDE.md`. Subsystem/package/workflow-specific rules go in that subtree's `CLAUDE.md`. If no suitable subtree orientation exists and several local critical rules would otherwise bloat the root, create a concise subtree `CLAUDE.md` and link it from the parent or root. 5. **Check coverage.** For each surviving constraint, ask two questions of the chosen orientation file: (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). 6. **Reinforce.** Edit the chosen `CLAUDE.md` so each crucial constraint is inline in the format below, with a signpost link. If the concise rule itself is too long to inline (or it's a shared critical doc), **`@import` it from the governing `CLAUDE.md`** instead of a plain link — transclusion guarantees it loads. 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 root `CLAUDE.md`, create a minimal one as the root. Ensure every created or maintained orientation file has an adjacent `AGENTS.md -> CLAUDE.md` symlink where symlinks are supported; if not, duplicate minimally and note the lockstep requirement. 7. **Report.** List what you hoisted inline, what went to root versus subtree orientation, 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. Each crucial constraint is one tight bullet in the selected orientation file: 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.

## 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 affected agent misses it; the link carries the full rationale and edge cases for expanded discovery. State the rule in exactly one inline home — root for repo-wide, subtree for local — and let the linked doc hold the rest: one idea, one home, with the headline as its earned inline exception.

- **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. If root bloat comes from local rules, prefer subtree orientation. - **Never clobber orientation.** 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. - **A plain link never carries a critical rule.** If a constraint must stay in its own file rather than inline, **`@import` it** (guaranteed transcluded into context), not `[link]` it (a pointer the agent may skip). Mind the locality cost: a *root* `@import` loads every session, so a rule critical only in a subtree belongs in that subtree's `CLAUDE.md` (auto-loaded on-interaction), not a root import. - **Keep harness compatibility.** Adjacent `AGENTS.md` symlinks should point to each loaded `CLAUDE.md` orientation where supported. - **Keep it grounded.** No speculative constraints — only rules with a real, traceable why.

<success_criteria>

• Every crucial design constraint in the repo is stated inline in the nearest loaded CLAUDE.md orientation that governs the affected area, 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.
• Root and subtree CLAUDE.md files stayed lean launchpads — only constraints that pass the three tests went inline; the rest stayed linked.
• Adjacent AGENTS.md symlinks exist for created or maintained orientation files where symlinks are supported, or a minimal lockstep fallback is documented.
• Existing orientation content is intact; nothing was clobbered. </success_criteria>

- **`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.