Skip to content

docs(agents): add simplicity + symmetric-defense conventions#267

Open
mgoldsborough wants to merge 1 commit into
mainfrom
docs/simplicity-conventions
Open

docs(agents): add simplicity + symmetric-defense conventions#267
mgoldsborough wants to merge 1 commit into
mainfrom
docs/simplicity-conventions

Conversation

@mgoldsborough
Copy link
Copy Markdown
Contributor

Summary

Six new convention bullets in `AGENTS.md` distilled from the QA round trips on PR #265 (heal-truncated-personal-workspaces). Captures the lessons that took multiple QA rounds to surface so the next PR can apply them at write time rather than discover them at review time.

Convention What it prevents
Less code is the goal Defensive accretion — a 50-line gate for a scenario the upstream code could be fixed to not produce
Symmetric defense "Happy path has the gate, new branch I just added doesn't" (PR #265 round-2 finding)
Refuse on conflict, never auto-merge Silent data loss when two states collide (the heal's original empty-stub gate)
Allowlist over denylist for safety gates New fields silently passing checks (PR #265 round-2 — `allowHttpProxy` missing)
Prefer fixing the cause over a bandaid The whole heal-script-as-bandaid pattern
Re-read PR body against diff before opening Drift findings (PR #265 round-2 — body claimed 9 tests when code had 14)

Each bullet is short, concrete, and references a real pattern site where applicable. Matches the existing AGENTS.md voice (short imperative bullets, no preamble).

Test plan

  • AGENTS.md renders cleanly (no broken markdown, no orphaned bullet)
  • CLAUDE.md symlink still points to AGENTS.md
  • No code paths affected — pure docs change

Related

  • PR feat(scripts): heal-truncated-personal-workspaces — Stage 1 follow-up #265 (the heal script whose QA rounds these conventions distill)
  • The Stage 1 lessons in `products/nimblebrain/nimblebrain-ops/research/delegation-model/REFACTOR_PLAN.md` already capture some related principles ("test the topology, not the API surface"); this PR makes them apply to code structure, not just tests.

Six new convention bullets distilled from PR #265's QA round trips:

- Less code is the goal — name the scenario each check prevents
- Symmetric defense — parallel paths get the same gates
- Refuse on conflict, never auto-merge — refusal is recoverable
- Allowlist over denylist for safety gates — future fields default to safe
- Prefer fixing the cause over a bandaid — heals are tech debt by construction
- Re-read PR body against diff before opening — pre-empts the drift findings

Each is concrete and references the pattern site. Captures the lessons
that took multiple QA rounds to surface in this session so the next PR
can apply them at write time rather than discover them at review time.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant