dubbl-a/house-rules

Revise docs

The official instruction-file management plugin ships a revise command that captures a session's learning by appending it to the root instruction file. That is the exact behavior this skill exists to replace. A root file that only grows stops getting read to the end, and a learning bolted onto it is rarely the fact a future session needed at the moment it needed it. This skill keeps the useful half of that plugin, auditing a claim against the codebase before writing it, and drops the append half in favor of routing. The harness's own machine-local memory notes already capture what a session learned and skip what the instruction files already say, so this skill routes the shareable, checked-in half instead: a rule to the rule file whose paths cover the surface it touches, an incident to the repo archive.

Default path

1. Name the thing this session produced that is worth keeping: a correction, a decided convention, a bug and its fix, a measured result, a decision between two approaches.
2. Classify it as a rule or an incident.
   • A rule holds every time a matching situation recurs. State it once and it should still be true after the next refactor.
   • An incident happened once, on a date, with a name or a measured number attached. It is evidence for why a rule exists, not the rule itself.
3. Route a rule to its matching rule file.
   • Search existing rule files by scope and heading, not by filename alone. Open the one whose paths: already covers the surface the learning touches.
   • If one covers it, add a new heading or fold the point into an existing one. Follow the rule shape: an imperative heading that is itself the rule, one clause of why, an Anchor: line naming what enforces it, a Receipts: line pointing at the archive entry, and keep the file ending in ## Don't.
   • Verify before writing. Check that every token in the Anchor: line, every path, every script name, actually resolves in the repo right now. This is the audit habit borrowed from the plugin above: never write a claim you have not checked.
   • If nothing covers it, say so and propose a new rule file or a wider scope for an existing one. Do not drop the point into the nearest file just because it is close.
4. Route an incident to the repo's archive tier.
   • The archive is whatever the repo calls its dated-evidence doc: a handbook chapter, a design-history file, a postmortem log. Write the date, the name, the measured number there, titled as a one-line lesson so the entry reads as a claim rather than a filename.
   • Point the rule file at the entry with its quoted heading. Do not restate the incident's specifics inside rule prose; a date or a number in a rule is history wearing a rule's clothes.
   • If the repo has no archive yet, say so and propose starting one. Do not fold the incident into a rule file or the root file for lack of a home.
5. Never touch the root instruction file. If neither a rule file nor the archive fits, that is a sign the fact is not durable enough to keep, not a reason to default it into the root file. Say that plainly and stop.
6. Show the edit before saving it. Print the heading and paragraph you propose, or a diff against the existing file, and wait for confirmation unless you were told plainly to just make the change.

When the match is a managed house rule

If the file that already covers the topic is a vendored house rule (carries the managed-file header, lives under .claude/rules/house/**), do not edit it in this repo. A local edit to a managed file is silently overwritten by the next /house-rules:sync run, and that silent loss is exactly what house exists to prevent.

Propose the change upstream instead. Draft the same heading and paragraph, then say to open it as a change in the house repo rather than this one. If the point is genuinely specific to this repo and not a fleet-wide rule, record it as a deviation in house.json instead of forking the managed file. Either path keeps the managed file in sync; editing it in place does not.

Escape hatches

• The learning contradicts an existing rule. Say so plainly, quote the existing heading, and ask which one wins before writing anything. Don't silently overwrite one rule with another.
• The learning is a repo-specific one-off with no rule shape, a workaround for a vendor bug, a note that only matters once. Route it to the archive as an incident instead of cluttering a rule file with something no future session needs to obey.
• You are unsure whether something is a rule or an incident. Bias toward the archive. A wrongly-archived rule is a heading someone can promote later; a wrongly-ruled incident becomes stale prose that nothing flags.
• The repo has no rule files and no archive at all. Say that plainly and stop rather than originating either one from inside this skill. That is /house-rules:bootstrap's job, not this one's.

Don't

• Don't append to the root instruction file. That is the exact behavior the official instruction-file plugin's revise command performs, and the reason this skill exists instead.
• Don't write a rule sentence whose anchor you have not checked against the codebase.
• Don't restate an incident's date, name, or number inside rule prose; point at the archive.
• Don't edit a vendored house rule file in place. Propose it upstream or record a deviation.
• Don't save an edit the person has not seen, unless they told you plainly to just make it.
• Don't invent a rule file or an archive when the repo has neither.