Repository navigation
Harness principle: guardrails over guidance (canonical in docs/, mirrored in constitution) - #228
Merged
Merged
Conversation
…#227) Documented best practice relies on a fallible human/agent remembering it; a deterministic gate does not. For costly or recurring mistakes, the durable fix is a gate (test, validation, lint rule, hook, CI check) — documentation alone is never the final answer (a stopgap doc ships with a filed `harness` issue to add the gate), and a near-miss caught only by inspection signals a missing gate. - constitution.md: new Principle VII (scoped NON-NEGOTIABLE: doc-alone is never the answer), cross-referenced from VI; version 1.3.0 → 1.4.0. - AGENTS.md + docs/contributing.md "Improving the harness": gate-first, kept consistent with the constitution (per Governance). Prompted by the #225 near-miss (visual-baseline staleness a doc wouldn't catch). Self-reviewed; findings addressed (scoped the NON-NEGOTIABLE tag to avoid contradiction with its own fallback; scoped to costly/recurring; noted Principle II still backstops). Closes #227 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
|
🔺 Vercel preview: https://cv-2n5ngab8v-bruno-valerios-projects.vercel.app commit |
The constitution is spec-kit-scoped (mainly in play under /speckit-*), so a principle that applies repo-wide shouldn't live there alone. Give it a canonical, tooling-agnostic home in docs/ and have everything point there. - NEW docs/engineering-principles.md — canonical "Guardrails over guidance" statement (rationale, "documentation alone is never the final answer", near-miss signals a missing gate, scope check, the gates we already run, II still backstops). - constitution.md Principle VII → concise mirror that points to the doc and notes it applies repo-wide (kept, per owner: "fine to be there as well"). - AGENTS.md + docs/contributing.md "Improving the harness" → point at the doc as canonical (mirrored as constitution Principle VII). - README.md + docs/README.md → index the new doc. Self-reviewed (two independent passes): cross-doc consistency, link/anchor resolution, and no contradiction with Principles II/IV all confirmed clean.
brunogbv
changed the title
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a governing principle: for costly or recurring mistakes, prefer a deterministic gate over a
documented practice. Prompted by the #225 near-miss (a stale visual baseline that no "be careful"
note would have caught — only a tightened gate). Closes #227.
Where it lives
The constitution is spec-kit-scoped (mainly in play under
/speckit-*), so a repo-wide principleshouldn't live there alone. The canonical home is a new tooling-agnostic doc; the constitution and
AGENTS.md mirror the essentials and point to it.
docs/engineering-principles.md— the canonical "Guardrails over guidance" statement:documentation states intent, a gate enforces it; documentation alone is never the final answer to
a real, recurring mistake (a stopgap doc ships with a filed
harnessissue); a near-miss caughtonly by inspection signals a missing gate; scope check ("not every one-off typo"); the gates we
already run; and that self-review (Principle II) still backstops.
.specify/memory/constitution.md— Principle VII kept as a concise mirror that points to the docand notes it applies repo-wide; version 1.3.0 → 1.4.0.
AGENTS.md+docs/contributing.md("Improving the harness") — "gate first", pointing at thedoc as canonical (mirrored as constitution Principle VII).
README.md+docs/README.md— index the new doc.Self-review
Two independent review passes across all 5 docs came back clean: canonical vs mirror is unambiguous and
consistent, every relative link/anchor resolves, the three gates are named correctly, and there's no
contradiction with Principle II (self-review) or IV (CI gates / no unit suite). Scoped the constitution's
(NON-NEGOTIABLE)tag to "documentation alone is never the final answer" so it doesn't conflict with itsown fallback. Docs-only; markdownlint clean.
This PR is the documentation of the principle; the actual gates it obligates us toward (starting with
#225, plus #221/#223/#216) are separate follow-up work — which is exactly the point.
🤖 Generated with Claude Code