diff options
| -rw-r--r-- | CLAUDE.md | 11 | ||||
| -rw-r--r-- | claude-rules/commits.md | 3 | ||||
| -rw-r--r-- | debug/SKILL.md | 10 | ||||
| -rw-r--r-- | todo.org | 14 |
4 files changed, 37 insertions, 1 deletions
diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3bce8b2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,11 @@ +# rulesets — project invariants + +## Canonical vs mirror + +`claude-templates/.ai/` is canonical; `.ai/` at the repo root is a committed mirror kept in sync by `scripts/sync-check.sh` (enforced by `githooks/pre-commit`). Always edit the canonical side, then run `scripts/sync-check.sh --fix` and commit both together. An edit made only in the `.ai/` mirror gets reverted by the next sync — it has happened, and the revert is silent. + +Same shape for language bundles: `languages/` is canonical; the `.claude/` copies installed into consuming projects are synced output, never edited in place. + +## Tests + +`make test` runs pytest + ERT + bats. Bats suites live in `scripts/tests/` and `.ai/scripts/tests/` and are glob-discovered, so new test files are picked up without Makefile edits. diff --git a/claude-rules/commits.md b/claude-rules/commits.md index 3bb6724..a3ec0f2 100644 --- a/claude-rules/commits.md +++ b/claude-rules/commits.md @@ -454,7 +454,8 @@ independent gate. 1. Check author identity: `git log -1 --format='%an <%ae>'` — should be the user. 2. Scan the message for AI-attribution language (including emojis and footers). 3. Review the diff — only intended changes staged; no unrelated files. -4. Run tests and linters (see `verification.md`). +4. Confirm staged files belong in the repo: nothing that the project's policy keeps untracked (the personal-tooling set in gitignore-mode projects), and in repos with a canonical/mirror split, the edit is on the canonical side — a mirror-only edit gets reverted by the next sync. +5. Run tests and linters (see `verification.md`). ## If You Catch Yourself diff --git a/debug/SKILL.md b/debug/SKILL.md index 4db6bbd..1db04df 100644 --- a/debug/SKILL.md +++ b/debug/SKILL.md @@ -36,6 +36,16 @@ Decide which kind of bug this is. Each branch hands off to the appropriate speci If two branches genuinely apply (a code bug also revealed a process gap), run both — the techniques are independent and complement each other. +### Hypothesis discipline — measure before theorizing (all branches) + +When the cause isn't obvious from Phase 1's evidence, do not narrate candidate causes and pick a favorite. Instead: + +1. **List the candidate causes**, each with the *single cheapest empirical test* that would confirm or kill it (a log read, a config dump, a timed measurement, an A/B toggle). +2. **Run the cheap tests first** — independent read-only probes go out as one parallel batch (parallel subagents when the probes are heavy). Rank by cost-to-test, not by how plausible the theory sounds. +3. **Report only confirmed findings.** A hypothesis with no passing test is not a finding, and never the basis for a fix. If every candidate dies, say "cause not isolated" and widen the evidence — don't promote the least-dead theory. + +This exists because serial hypothesis-cycling (VPN? GPU? firewall? DNS?) burns user cycles on theories a one-line measurement would have killed. Extended empirical monitoring (a battery-drain log, a before/after timing) beats a clever-sounding explanation every time. + ## Phase 3 — Verify the Hypothesis Once the chosen specialist has produced a hypothesis: @@ -139,6 +139,20 @@ Expected: all four behave per the spec; any miss promotes to a bug task. (Agent- *** 2026-06-10 Wed @ 18:21:33 -0500 Phase 4 done — monthly hygiene automation live =scripts/kb-hygiene.sh= (6 bats green, shellcheck clean, read-only by design) inventories =:agent:= nodes, flags orphans / duplicate titles / conflict files, and writes an org report into the rulesets inbox; =roam-hygiene.timer= (monthly, Persistent) installed + enabled. Live run against the real KB verified (4 agent nodes, 428 files, 0 conflicts). Conditional vNext stays in the spec's scope tiers: a =/promote= command if the wrap-up prompt proves insufficient, an =:agent:inbox:= staging tag if free writes prove too noisy. Commit b014095. +** TODO [#C] Morning ops orchestrator pilot — read-only :feature: +:PROPERTIES: +:CREATED: [2026-06-11 Thu] +:LAST_REVIEWED: 2026-06-11 +:END: +A scheduled headless morning run chaining the existing pieces: startup checks, the triage-intake scan, a system health check — producing the prep doc plus a report and a notify ping, with all remediation propose-only. Staged adoption from the 2026-06-11 insights report's "Self-Healing Daily Ops Orchestrator": read-only first; promote individual routine remediations to auto only after each has a track record. Known blockers to design around: headless MCP auth (interactively-authenticated servers are absent in cron runs) and the consent boundary (triage Phase D, anything destructive). + +** TODO [#C] Monthly session-harvest workflow :feature: +:PROPERTIES: +:CREATED: [2026-06-11 Thu] +:LAST_REVIEWED: 2026-06-11 +:END: +A monthly pass over recent =.ai/sessions/= summaries across projects proposing promotion candidates: patterns for the catalog, durable facts for the KB, rule refinements, workflow learnings. Sibling cadence to the roam-hygiene timer; a workflow run on schedule, not a standing agent. From the 2026-06-11 insights report's "Canonical-Aware Knowledge & Workflow Curator" — the capture/promote machinery exists (pattern catalog, /codify, KB); this adds the mining cadence. + ** TODO [#C] Build =create-documentation= skill for high-quality project/product docs :feature: :PROPERTIES: :LAST_REVIEWED: 2026-06-10 |