Tighten comment discipline + require feature branch for tdd skills#8
Open
ai-agent-lead wants to merge 6 commits into
Open
Tighten comment discipline + require feature branch for tdd skills#8ai-agent-lead wants to merge 6 commits into
ai-agent-lead wants to merge 6 commits into
Conversation
- Fix duplicated headers and corrupted tails in tdd-rounds, code-hygiene, and WORKFLOWS.md - Create docs/CONTEXT.md defining the AI Agent Skills domain - Add docs/adr/0001-distributed-state.md recording the TDD rounds state refactor - Add docs/features/distributed-state.md documenting the feature scope
Sharpen the canonical comment rules so agent-produced code carries fewer comments by default. Docstrings on exported identifiers are no longer required — written only when the contract isn't obvious from the signature. Trade-off and provenance comments are kept only when the next reader would otherwise reattempt the rejected alternative. Adds in-function section headers as a sixth "delete on sight" pattern. Aligns the enforcement points (code-hygiene during writing, simplify during sweep, pr-review at review) so the bias is consistent end-to-end. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Code lands on feat/<name> or fix/<name>; main receives merges, not commits. feature-doc's Done-when now requires the branch to be checked out before the contract doc is committed. tdd adds a Pre-conditions block that refuses to start if HEAD is main / master. tdd-rounds requires the parent to dispatch on a feature branch and the Builder to verify and refuse if on main. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a root-level CHANGELOG.md following Keep-a-Changelog, seeded from git history through v1.2.0. Adds one bullet to prod-ready Section 7 requiring an [Unreleased] entry for any user-visible change; skip list matches feature-doc. Replaces ad-hoc commit-log archaeology with a single readable artifact. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Four reviewers (Skeptic / Pragmatist / Editor / Architect) ran in parallel; a fifth judge weighed the contested STATE.md drift. This commit applies the consensus fixes. Numbering / corruption: - code-hygiene now declares "Six principles" (was Five) and the summary list gains the missing Principle 6 bullet - pr-review §3e (hygiene) renumbered to §3f to disambiguate from the doc-drift audit also labeled §3e above it - WORKFLOWS.md cross-workflow item renumbered 12 -> 15 (was duplicate) - skills/README.md "Adding a skill" step 7 orphan fragment removed Cross-skill consistency: - prod-ready stops claiming "same skip list as feature-doc" (it was not the same); inlines its own canonical list - pr-review §3e doc-drift audit gains a CHANGELOG check to mirror prod-ready Section 7's new item - feature-doc Done-when reordered so the branch check precedes reviewer sign-off - tdd-rounds Builder gets a dedicated step 0 (pre-flight branch check) so refusal can't be lost inside the context-loading step ADR-0001 (distributed state) — judge picked Option B: - ADR keeps Status: accepted but adds Alternatives Considered and an Implementation status section flagging skill-text drift - features/distributed-state.md ACs reset to [ ] with a Status header pointing to docs/known-issues.md - docs/known-issues.md bootstrapped to track the follow-up - CHANGELOG: distributed-state bullet moves from [1.2.0] Changed to [Unreleased] with honest "accepted; migration pending" wording - WORKFLOWS.md artifacts table marks the feature-scoped rows as target end-state until the follow-up lands STYLE-comments polish: - §1.3 examples relabeled by kind (Invariant / Constraint / Trade-off / Provenance) to match the four-noun section title, restoring the explicit Provenance label folded out of the old §1.5 - §1.2 third bullet broadened to cover nil-as-meaning (`(nil, nil) = "not found"`), not just zero-as-meaning - "documented for the next reader" parenthetical dropped from the Trade-off example since the old §5 it referenced is gone CHANGELOG categorization (per Keep-a-Changelog): - branch-rule and sixth "delete on sight" pattern moved from Added to Changed (they tighten existing skills, not add capabilities) docs/CONVENTIONS.md gains Branches, Commits, and Code Style sections so the conventions now enforced by four skills also live in one canonical place. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
STYLE-comments.mdand align enforcement points (code-hygiene,simplify,pr-review) so agent-produced code carries fewer comments by default. Docstrings on exported identifiers are no longer required — written only when the contract isn't obvious from the signature. Trade-off / provenance comments are kept only when the alternative would otherwise be reattempted. Adds in-function section headers as a sixth "delete on sight" pattern.feat/<name>orfix/<name>) beforetdd,tdd-rounds, orfeature-docstart.mainreceives merges, not commits.CHANGELOG.mdat repo root (Keep-a-Changelog format) from git history through v1.2.0, and add aprod-readySection 7 item that requires a[Unreleased]entry for any user-visible change (skip list matchesfeature-doc).d620b85,709cefe) that had been committed directly tomain— they now live on this branch and reachmainonly via merge of this PR.Commits
709cefedocs: fix skill file corruption and bootstrap repo docs (docs/CONTEXT.md,docs/adr/0001-distributed-state.md,docs/features/distributed-state.md)d620b85docs: createdocs/CONVENTIONS.mdto satisfy README references572e361docs(skills): tighten comment discipline to bias against agent output9481b12feat(skills): require feature branch for tdd, tdd-rounds, feature-docb8cf8c9docs(release): seed CHANGELOG.md and wire it into prod-ready Section 7Review checklist
STYLE-comments.mdreads consistently end-to-end; §5 ("Documented for the next reader") was folded into §1.3 — confirm nothing dangling references it.code-hygienePrinciple 6,simplify§2 (Quality), andpr-review§3e all point atSTYLE-comments.mdwith the same bias.feature-docDone when,tddPre-conditions, andtdd-roundsparent + Builder contracts all encode the non-mainbranch rule.CHANGELOG.md[Unreleased] entries match the actual commits on this branch.Heads-up for collaborators
mainwas force-pushed to removed620b85and709cefe. Anyone whose localmainhad them needs:```
git fetch && git reset --hard origin/main
```
The two commits are not lost — they're at the base of this branch.
🤖 Generated with Claude Code