docs: add workflow standards - #32
Conversation
|
Warning Review limit reached
More reviews will be available in 24 minutes and 51 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more credits in the billing tab to continue. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
xtask/src/main.rs (1)
170-190: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winCentralize test-plan status validation for case rows too.
case.statusand requirement status use separate allowlists. Reuseis_known_test_plan_statusin the case match to prevent future drift between these contracts.Suggested refactor
- match case.status.as_str() { - "implemented" => { + match case.status.as_str() { + "implemented" => { if case.evidence.trim().is_empty() || case.evidence.trim() == "-" { return Err(format!("{} is implemented without evidence", case.id)); } for evidence in split_cell_list(&case.evidence) { let test_name = evidence.rsplit("::").next().unwrap_or(evidence); if !tests.contains(test_name) { return Err(format!( "{} evidence `{}` does not match a Rust test function", case.id, evidence )); } } for requirement in split_cell_list(&case.requirement) { implemented_requirements.insert(requirement.to_owned()); } } - "planned" | "gap" | "policy" => {} + status if is_known_test_plan_status(status) => {} other => return Err(format!("{} has invalid status `{other}`", case.id)), }Also applies to: 226-228
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@xtask/src/main.rs` around lines 170 - 190, The case-row status match in the validation logic duplicates the test-plan status allowlist, so it can drift from the shared contract. Update the match on case.status in the main validation flow to reuse is_known_test_plan_status, just like the requirement-status check, and keep the implemented branch handling unchanged except for using the shared predicate before classifying unknown statuses.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/topics/documentation/README.md`:
- Around line 8-10: The README text currently hardcodes a machine-local absolute
path in the documentation standards reference, which is not portable. Update the
wording in the affected README section to use a repository-relative path or a
generic plain-text reference instead of the `/Users/james/...` path, keeping the
intent tied to the documentation standards mention.
---
Outside diff comments:
In `@xtask/src/main.rs`:
- Around line 170-190: The case-row status match in the validation logic
duplicates the test-plan status allowlist, so it can drift from the shared
contract. Update the match on case.status in the main validation flow to reuse
is_known_test_plan_status, just like the requirement-status check, and keep the
implemented branch handling unchanged except for using the shared predicate
before classifying unknown statuses.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: ddff1bb5-a7ed-47f0-a8bf-462945f98e16
📒 Files selected for processing (10)
AGENTS.mdCONTRIBUTING.mdREADME.mddocs/README.mddocs/topics/README.mddocs/topics/documentation/README.mddocs/topics/documentation/test-plan.mddocs/topics/tests/README.mddocs/topics/tests/test-plan.mdxtask/src/main.rs
📜 Review details
🧰 Additional context used
📓 Path-based instructions (2)
docs/topics/**
📄 CodeRabbit inference engine (AGENTS.md)
docs/topics/**:docs/topics/is the living contract graph for landed behavior; topic shelves are not proposals, retrospectives, or design archaeology.
For every nontrivial behavior, contract, workflow, release, schema, validation, or public-surface change, identify the owning topic shelf before editing code, create one if none exists, and update itstest-plan.mdbefore or alongside tests with requirement IDs, case IDs, fixtures, and oracles.
Update the topicREADME.mdonly after the behavior exists in the branch; the README must describe current branch truth, not intended future behavior.
Mark planned cases intest-plan.mdas implemented only when executable evidence exists.
TopicREADME.mdfiles must not describe intended behavior before it lands.
test-plan.mdmay include planned cases and known gaps.
policyrows are for human-review workflow contracts and must not be used to avoid writing behavior tests for software behavior.
Tests must assert code behavior and stable contract artifacts, not prose, repository structure, implementation detail, or documentation detail.
When creating or changing documentation, give each page one primary reader job, keep user-facing task help separate from contributor architecture and evidence maps, use concrete valid examples, and put exact public facts in reference material when practical.
Update affected documentation in the same change as behavior, schema, release, workflow, or public-surface changes, or statedocs-impact: nonewith a concise rationale.
Files:
docs/topics/documentation/test-plan.mddocs/topics/tests/test-plan.mddocs/topics/tests/README.mddocs/topics/documentation/README.mddocs/topics/README.md
**
⚙️ CodeRabbit configuration file
**: # AGENTSGit Rules
NEVER amend git commits. Make a new commit instead.
NEVER use
git rebaseunless the user explicitly approves a rare exception.
Use regular merge commits.NEVER force any git operation. If a force operation appears necessary, stop and
explain what happened and what options remain.NEVER create draft pull requests.
NEVER use a
codexprefix in branch names, PR titles, or commit messages.Pull request bodies for issue work MUST include GitHub auto-close text such as
Closes#123`` for every issue the PR is intended to close.Think
Think is durable memory for cross-session coordination.
- Use
codex-think --remember --jsonwhen starting a new session, changing into
this repository, or regaining context after a context shift.- Use
codex-think "..." --jsonwhen a cycle closes or a significant event
should survive across turns.- Treat Think as memory, not repo truth. Anchor strong claims back to files,
commits, commands, issues, or pull requests.- Claude memories are read-only. Use
claude-think --remember --jsononly for
additional context.Topic Shelves
docs/topics/contains the living contract graph for landed behavior. Topic
shelves are not proposals, retrospectives, or design archaeology.Each shelf may contain:
README.md: what is true in HEAD.test-plan.md: how those truths are verified, including requirements, cases,
fixtures, oracles, implemented evidence, planned cases, and known gaps.architecture.md: optional structure or dataflow notes when the machinery
earns a separate page.rationale.md: optional still-relevant tradeoffs and rejected approaches.When To Update Topic Shelves
For every nontrivial behavior, contract, workflow, release, schema, validation,
or public-surface change:
- Identify the owning topic shelf before editing code.
- If no shelf owns durable behavior, create one.
- Update
test-plan.mdbefore or alongside tests with requirement IDs, case
IDs,...
Files:
docs/topics/documentation/test-plan.mddocs/README.mdCONTRIBUTING.mddocs/topics/tests/test-plan.mddocs/topics/tests/README.mddocs/topics/documentation/README.mdAGENTS.mddocs/topics/README.mdREADME.mdxtask/src/main.rs
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Never amend git commits; make a new commit instead.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Never use `git rebase` unless the user explicitly approves a rare exception; use regular merge commits.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Never force any git operation; if a force operation appears necessary, stop and explain what happened and what options remain.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Never create draft pull requests.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Never use a `codex` prefix in branch names, PR titles, or commit messages.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Pull request bodies for issue work must include GitHub auto-close text such as `Closes `#123`` for every issue the PR is intended to close.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Use `codex-think --remember --json` when starting a new session, changing into this repository, or regaining context after a context shift.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Use `codex-think "..." --json` when a cycle closes or a significant event should survive across turns.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Treat Think as memory, not repository truth; anchor strong claims back to files, commits, commands, issues, or pull requests.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Claude memories are read-only; use `claude-think --remember --json` only for additional context.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: For behavior, contract, workflow, release, schema, validation, or public-surface changes, use RED/GREEN test-driven development: update the owning topic `test-plan.md` first or alongside the first test, write the deterministic test before implementation, run the narrowest relevant command and observe the RED failure, implement the smallest coherent change, then mark rows implemented only after executable evidence exists.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Report the RED command and GREEN command in the final report or pull request body.
Learnt from: CR
Repo: flyingrobots/edict
Timestamp: 2026-06-24T14:46:42.908Z
Learning: Use the local gate `cargo xtask verify` before claiming a branch is ready.
🪛 LanguageTool
docs/topics/documentation/test-plan.md
[style] ~73-~73: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...r maps public surfaces to page types. - No executable tutorial harness exists beca...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (10)
xtask/src/main.rs (1)
151-153: LGTM!Also applies to: 200-200, 640-696
AGENTS.md (1)
77-78: LGTM!Also applies to: 87-133
CONTRIBUTING.md (1)
1-40: LGTM!docs/topics/tests/README.md (1)
1-84: LGTM!README.md (1)
476-478: 📐 Maintainability & Code QualityNo change needed The compiler-spine API names already match current exports and usages.
docs/topics/tests/test-plan.md (1)
1-73: LGTM!docs/topics/documentation/README.md (1)
14-117: LGTM!docs/topics/documentation/test-plan.md (1)
1-75: LGTM!docs/README.md (1)
10-13: LGTM!docs/topics/README.md (1)
22-25: LGTM!Also applies to: 38-47
|
Code Lawyer self-audit found one additional issue beyond the actionable CodeRabbit findings.
Cc @codex for second opinion. |
|
Codex Review: Didn't find any major issues. Another round soon, please! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Code Lawyer Activity Summary
Validation:
Notes:
|
1 participant
Summary
/Users/james/git/DOCUMENTATION_STANDARDS.mdfor Edict's topic-shelf/spec/release workflow.CONTRIBUTING.mdas the human contributor entry point.policytopic test-plan status support so human-review workflow policies are not misrepresented as executable software evidence.Testing
policystatus behavior:cargo test -p xtask contract_graph_ -- --nocapturefailed before implementation becausepolicyrows were rejected and unknown requirement statuses were accepted.cargo test -p xtask contract_graph_ -- --nocapturecargo xtask verifymarkdownlint-cli2 AGENTS.md docs/topics/README.md docs/topics/tests/README.md docs/topics/tests/test-plan.md docs/topics/documentation/README.md docs/topics/documentation/test-plan.mdNotes