crashlabs/huskies
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 27 Wiki Activity

docs(AGENT.md): forceful "no exceptions" doc-comment rule

Browse Source 
Two stories today (961, 962) passed every other gate and got bounced
at the merge step on a single missing `///` on a `pub mod` line.
Sonnet keeps treating the doc comment as optional when the rule says
"add doc comments to new modules and pub functions/structs/enums."

Promote the rule to its own loud section with no-exceptions wording
and a concrete reminder to run source-map-check before committing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
dave
2026-05-13 12:08:54 +00:00
parent 184c214c34
commit 3c9851d17d
1 changed files with 8 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.huskies/AGENT.md
+8
View File
@@ -47,6 +47,14 @@ Required sections:
A PLAN.md that contains only generic steps like "read the code", "write the code", "run the tests", or leaves file paths as `<TBD>` or unspecified is **non-conforming**. Every AC entry must name a real file path and describe the actual change. Every decision entry must name both the chosen approach and at least one rejected alternative with a reason. A stub plan is worse than no plan — rewrite it with specifics.
## Doc comments — your merge will fail if you skip even one
Every time you introduce a NEW public item — `pub mod X`, `pub fn`, `pub struct`, `pub enum`, `pub trait`, `pub const`, `pub static`, `pub type`, or a `mod X;` declaration that introduces a new module file — the line directly above it **MUST** be a doc comment starting with `///` (or `//!` at the top of a new module file).
There are no exceptions. The merge gate runs `source-map-check` and rejects the merge for any single missing doc comment. Two stories today (961, 962) passed every test, every clippy check, and every other gate, then got bounced at the final step because of one missed `///` on a `pub mod` line. **Treat the `///` as part of writing the declaration, not as an afterthought.**
Before committing, run `cargo run -p source-map-gen --bin source-map-check -- --worktree . --base master` and address every missing-docs direction it prints. If you added a new module file (e.g. `foo.rs` or `foo/mod.rs`), the FIRST line of that file MUST be a `//! What this module is for` doc comment.
## Documentation
Docs live in `website/docs/*.html` (static HTML), **not** Markdown files. When a story asks you to document something, edit the relevant `.html` file in `website/docs/`.