From 7c8380e54739901e6f7e6c37f13acca669e3b881 Mon Sep 17 00:00:00 2001 From: Oleg Date: Thu, 14 May 2026 00:56:55 -0700 Subject: [PATCH] chore: carve out docs/review/ as a tracked subdirectory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds an explicit ``!docs/review/`` negation in .gitignore so curated review/authoring heuristics can live in-repo alongside the source they shape. Everything else under ``docs/`` (loose design notes, scratch investigation files, etc.) stays gitignored by the new ``docs/*`` pattern. Note: the negation requires the parent pattern to match contents (``docs/*``), not the directory (``docs/``). Git won't descend into an excluded directory to honour child negations, so the previous ``docs/`` line had to be widened. A placeholder ``docs/review/README.md`` is included so the directory is real and the carve-out has something to track. The shared review heuristics doc itself lands in a follow-up PR (drafted locally by Pushok during PR #496's iteration) to keep the carve-out review separate from the content review. Minimal-scope by design — additional tracked docs subdirs (``!docs/architecture/`` etc.) can carve out in their own small PRs when there's real content to land. Co-Authored-By: Claude Opus 4.7 --- .gitignore | 7 ++++++- docs/review/README.md | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 docs/review/README.md diff --git a/.gitignore b/.gitignore index f3501744..18cb9589 100644 --- a/.gitignore +++ b/.gitignore @@ -26,7 +26,12 @@ stitch/ skills/.gitkeep skills/* website/ -docs/ +# Curated docs that should live in-repo carve out of the gitignore. +# Pattern is ``docs/*`` (contents) + explicit ``!docs//`` +# negations — NOT ``docs/`` (directory), because git won't descend into +# an excluded directory to honour child negations. +docs/* +!docs/review/ heartbeat.log .coverage output/ diff --git a/docs/review/README.md b/docs/review/README.md new file mode 100644 index 00000000..789ccec9 --- /dev/null +++ b/docs/review/README.md @@ -0,0 +1,39 @@ +# Review heuristics + +This directory holds shared review and authoring heuristics for the agent +pool — frameworks that compound across PRs when every agent applies the +same checklist at *write* time, not just at review time. + +## Why this directory is tracked + +`docs/` is gitignored by default so scratch design notes and local-only +investigation don't accidentally get committed. `docs/review/` is carved +out as an explicit tracked subdir because the heuristics here are +intended to outlive any single PR and to be discoverable next to the +source they shape. + +If you want to add another always-tracked docs subdirectory in the +future, follow the same pattern: add `!docs//` to `.gitignore` +in its own small PR, then ship the actual content separately so the +review of the carve-out doesn't get tangled with the review of the +content. + +## Current docs + +- _Placeholder — heuristics doc landing in a follow-up PR._ + +## Adding a new heuristic + +Heuristics earn their place by surviving the same discipline they +impose: + +1. **n=2 cross-domain** for case-shaped detectors (mechanical detectors + for bug-shape patterns). +2. **Mechanical detector required** — broad pattern recognition without + a detector belongs in an open-observations appendix, not a numbered + case. +3. **Self-application** — if the framework can't survive being applied + to itself, it's not strong enough yet. + +Open observations (n=1 candidates) and case candidates that lack sharp +detectors live in appendices, not the main framework.