feat: add adr skill#123
Open
tigra wants to merge 2 commits into
Open
Conversation
Adds an opt-in /awos:adr command that captures an Architecture Decision Record — context, alternatives considered, decision, rationale, and consequences — saved as a numbered file under context/adr/. Bulleted sections (pros/cons, consequences, references) are confirmed by the user via multi-select rather than auto-authored. - commands/adr.md + claude/commands/adr.md wrapper - templates/adr-template.md - integration hooks: architecture.md (offer ADRs after a material architecture change) and tech.md (offer ADRs for architectural choices in a tech spec). Both hooks are opt-in — the skill opens with a skip option, so existing flows are unchanged unless the user opts in.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughAdds an ADR command, a reusable ADR template, a stepwise ADR capture workflow (opt-in, context, alternatives, rationale, consequences, review, save), and optional hooks into architecture and tech workflows to offer ADR logging when architecture changes are meaningful. ChangesADR Command System
🎯 3 (Moderate) | ⏱️ ~20 minutes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
commands/adr.md (1)
49-188:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd explicit Creation Mode / Update Mode flow.
The command currently defines one capture flow, but it does not explicitly support both
required modes (Creation Modefor new ADRs andUpdate Modefor existing ADRs) as a
first-class contract.Proposed patch
# PROCESS +## Mode selection (run before Step 0) + +Use `AskUserQuestion` to choose: + +- `Creation Mode — create a new ADR` +- `Update Mode — revise an existing ADR` + +Rules: + +- Always produce exactly one output document for this command run. +- In Creation Mode, follow Steps 0–9 and write `context/adr/NNN-<slug>.md` (or `_pending.md` on defer). +- In Update Mode, select one existing ADR from `context/adr/*.md` (excluding `_pending.md`), load it, and run the same interview flow as targeted edits; preserve ADR number/filename unless the user explicitly requests a title/slug rename. + ## Universal principles (apply to every step below)As per coding guidelines: "
commands/**/*.md... Commands must support both 'Creation Mode' for new documents and 'Update Mode' for existing documents, generating a single output document per command".
🤖 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 `@commands/architecture.md`:
- Line 74: The "Offer ADR(s) (optional)" step currently instructs invoking the
ADR skill inline (via `.awos/commands/adr.md` / AskUserQuestion) which can
produce additional output files and breaks the single-output rule; change the
text so `/awos:architecture` only suggests ADR creation as a follow-up or
explicit user-triggered handoff (e.g., "To record ADRs, run the ADR command:
`.awos/commands/adr.md`" or "Would you like to open the ADR creation command?")
and remove any instruction to automatically invoke the ADR skill or perform ADR
creation inline, ensuring the command generates a single output document
(architecture.md) only.
In `@commands/tech.md`:
- Line 94: The current step "Offer ADR(s) (optional)" directly invokes ADR
capture and can create extra files under /awos:tech; change it to suggest the
next command instead of executing it inline by replacing the in-flow ADR
invocation with a suggestion like "suggest next command: `/awos:adr
<user_prompt>`" (reference the step heading "Offer ADR(s) (optional)" and the
`/awos:adr` skill name) so the command output remains a single document
(technical-considerations.md) and ADR creation becomes an explicit user-invoked
follow-up.
🪄 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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 4b846b69-18ea-4187-b181-45bbffefd9f4
📒 Files selected for processing (5)
claude/commands/adr.mdcommands/adr.mdcommands/architecture.mdcommands/tech.mdtemplates/adr-template.md
|
|
||
| 1. Write the final content to `context/product/architecture.md`. | ||
| 2. Proceed to **Step 4: Coverage Hint**. | ||
| 2. **Offer ADR(s) (optional):** If the architecture was meaningfully changed (creation mode, or a material update — not a typo fix), follow the instructions in `.awos/commands/adr.md` to optionally log one or more ADRs capturing the architectural decisions just made (e.g., the chosen tech stack components, deployment target, data store, security posture, region — anything where a real alternative was considered). Pass a short note as `<user_prompt>` describing the trigger, e.g. `"architecture.md §[section] — chose [tech/pattern] over [alternative]"`. The ADR skill itself opens with an `AskUserQuestion` skip option, so simply invoke it; the user may decline or defer at that prompt. After it returns (whether logged, skipped, or deferred), continue. |
There was a problem hiding this comment.
Keep /awos:architecture single-output; don’t execute ADR creation inline.
This step makes the command potentially write multiple documents (architecture.md plus ADR files), which breaks the framework contract for core commands. Keep ADR as a suggested next command (or explicit user-triggered handoff) instead of invoking it inside this flow.
As per coding guidelines, "commands/**/*.md ... [must] generat[e] a single output document per command."
🤖 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 `@commands/architecture.md` at line 74, The "Offer ADR(s) (optional)" step
currently instructs invoking the ADR skill inline (via `.awos/commands/adr.md` /
AskUserQuestion) which can produce additional output files and breaks the
single-output rule; change the text so `/awos:architecture` only suggests ADR
creation as a follow-up or explicit user-triggered handoff (e.g., "To record
ADRs, run the ADR command: `.awos/commands/adr.md`" or "Would you like to open
the ADR creation command?") and remove any instruction to automatically invoke
the ADR skill or perform ADR creation inline, ensuring the command generates a
single output document (architecture.md) only.
| 1. **Identify Path:** The output path is the `technical-considerations.md` file inside the directory you identified in Step 1. | ||
| 2. **Save File:** Once the user approves the draft, write the final content into this file. | ||
| 3. Review the saved spec for new technologies, frameworks, tools, or testing approaches not already covered by the project's existing architecture and specialist agents. | ||
| 3. **Offer ADR(s) (optional):** Review the saved technical considerations for **architectural choices** that don't already have an ADR — for example, picking a new datastore, a new service, a new pattern, a new vendor, a region, an auth model, or a non-trivial trade-off where a real alternative was considered. For each such choice not already captured, follow the instructions in `.awos/commands/adr.md` to optionally log an ADR. Pass a short note as `<user_prompt>` describing the trigger, e.g. `"technical-considerations.md (spec [name]) — chose [tech/pattern]"`. The ADR skill itself opens with a skip option, so simply invoke it; the user may decline or defer. Skip this step entirely if the tech spec is purely follow-on detail of decisions already covered by existing ADRs. |
There was a problem hiding this comment.
Avoid multi-document writes inside /awos:tech.
Running ADR capture from this step can produce extra files beyond technical-considerations.md, violating the one-command/one-output rule. Please switch this to a “suggest next command: /awos:adr ...” pattern rather than in-flow execution.
As per coding guidelines, "commands/**/*.md ... [must] generat[e] a single output document per command."
🤖 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 `@commands/tech.md` at line 94, The current step "Offer ADR(s) (optional)"
directly invokes ADR capture and can create extra files under /awos:tech; change
it to suggest the next command instead of executing it inline by replacing the
in-flow ADR invocation with a suggestion like "suggest next command: `/awos:adr
<user_prompt>`" (reference the step heading "Offer ADR(s) (optional)" and the
`/awos:adr` skill name) so the command output remains a single document
(technical-considerations.md) and ADR creation becomes an explicit user-invoked
follow-up.
AlexanderMakarov
pushed a commit
that referenced
this pull request
Jul 2, 2026
Squash/rebase-merging a PR leaves no merge commit, so every metric built on `git log --merges` silently read 0 on healthy repos, and per-author merge counts credited only whoever clicked the merge button (dossier 03-squash-merge-blind-spot.md). - The git collector now counts squash-merged PRs as merge events: first-parent non-merge trunk commits carrying a forge PR ref — GitHub "Title (#123)", Azure DevOps "Merged PR 123: …", Bitbucket "(pull request #12)", GitLab "See merge request …!45" in the body — attributed to the commit author, which for a squash merge IS the PR author. window_stats gains merge_commits / squash_merges / merge_strategy (merge-commit | squash | mixed | unknown). - Deploy frequency, change-failure rate, and rework rate now measure squash repos correctly (their revert/fix keyword filters cover the squashed subjects too). - Lead time, PR cycle time, and review rework are merge-record proxies that cannot exist without real merge commits: on a squash-strategy repo they SKIP with a connector-pointing reason instead of reporting a confident number from unrepresentative residue. The MTTR git proxy stays included (per its contract) but degrades confidence with an explanatory note. - activeContributors: merge-share now includes squash events, restoring the safety valve on squash repos; when a repo has no merge events at all, commit-share replaces merge-share so the rule can't degenerate to LOC-share-only (the '1 active of 9' collapse). Validated on the dossier's evidence repo: 19 merges credited to one maintainer → 114 merge events across the 4 real PR authors, strategy=squash. Claude-Session: https://claude.ai/code/session_014UpLfgFPaACkrEUuk7CGiF
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.
What
Adds an opt-in
/awos:adrcommand that captures an Architecture Decision Record — context, alternatives considered, decision, rationale, and consequences — saved as a numbered file undercontext/adr/.A defining property: every bulleted section (pros/cons of each alternative, consequences, references) is confirmed by the user via multi-select, not auto-authored — the skill seeds candidate bullets and only the ones the user selects (plus free-text additions) land in the file.
Files
commands/adr.md+claude/commands/adr.mdwrappertemplates/adr-template.mdcommands/architecture.md— offer ADR(s) after a material architecture changecommands/tech.md— offer ADR(s) for architectural choices captured in a tech specBackward compatibility
Both hooks are opt-in: the skill opens with an
AskUserQuestionskip option, so existingarchitecture/techflows are unchanged unless the user opts in.Validation
npm test→ 69/69 passnpx prettier --check .cleanSuggested release-drafter label: minor (new feature skill).
Summary by CodeRabbit
New Features
Documentation