Is your feature request related to a problem? Please describe.
The cueckoo common guidance "Commit Messages" section says the first line is "prefixed by the primary affected package or area." All three examples are Go packages (cue/ast/astutil, cmd/cue, internal/core/adt), and the section never says what the prefix should be for changes to files that aren't part of any package — top-level or tooling config such as CLAUDE.md, .claude/, codereview.cfg, documentation, or CI config.
In practice this ambiguity led an AI assistant, while configuring a repo to follow the guidance, to search git history for "prior art" to choose a prefix rather than deriving it from the rule. That is wasted effort, and worse, it risks treating an earlier non-conforming commit as binding precedent — the opposite of the guidance being the source of truth.
Describe the solution you'd like
Add a sentence to the "Commit Messages" section (after the examples) covering non-package files, e.g.:
For changes to files that are not part of a package — top-level or tooling config such as CLAUDE.md, .claude/, codereview.cfg, docs, or CI config — use the affected file or directory path(s) as the area, comma-separated when several apply (for example CLAUDE.md,.claude:).
This removes the ambiguity at its source, so the prefix can be derived from the rule alone.
Describe alternatives you've considered
- Adding a rule that says "do not reverse-engineer conventions from git history." Rejected: it is a negative meta-instruction that is hard to scope (history is sometimes the right place to look), does not generalize cleanly, and bloats shared guidance to patch what is really a judgment call. That belongs in an assistant's local memory, not the common guidance.
- Doing nothing. The convention is discoverable from history, but leaving it unwritten reproduces the same wasted-effort and precedent risk each time.
Additional context
Surfaced while updating the cue-labs/services repo to use the @~/.cache/cueckoo/common-guidance.md @-import and the cueckoo version update SessionStart hook. The resulting commit used the prefix CLAUDE.md,.claude:, which matches the proposed wording.
Is your feature request related to a problem? Please describe.
The cueckoo common guidance "Commit Messages" section says the first line is "prefixed by the primary affected package or area." All three examples are Go packages (
cue/ast/astutil,cmd/cue,internal/core/adt), and the section never says what the prefix should be for changes to files that aren't part of any package — top-level or tooling config such asCLAUDE.md,.claude/,codereview.cfg, documentation, or CI config.In practice this ambiguity led an AI assistant, while configuring a repo to follow the guidance, to search git history for "prior art" to choose a prefix rather than deriving it from the rule. That is wasted effort, and worse, it risks treating an earlier non-conforming commit as binding precedent — the opposite of the guidance being the source of truth.
Describe the solution you'd like
Add a sentence to the "Commit Messages" section (after the examples) covering non-package files, e.g.:
This removes the ambiguity at its source, so the prefix can be derived from the rule alone.
Describe alternatives you've considered
Additional context
Surfaced while updating the
cue-labs/servicesrepo to use the@~/.cache/cueckoo/common-guidance.md@-import and thecueckoo version updateSessionStart hook. The resulting commit used the prefixCLAUDE.md,.claude:, which matches the proposed wording.