feat(skills): add architecture-decision-records skill#555
Open
vazidmansuri005 wants to merge 6 commits intoaffaan-m:mainfrom
Open
feat(skills): add architecture-decision-records skill#555vazidmansuri005 wants to merge 6 commits intoaffaan-m:mainfrom
vazidmansuri005 wants to merge 6 commits intoaffaan-m:mainfrom
Conversation
Adds a skill that captures architectural decisions made during coding sessions as structured ADR documents (Michael Nygard format). Features: - Auto-detects decision moments from conversation signals - Records context, alternatives considered with pros/cons, and consequences - Maintains numbered ADR files in docs/adr/ with an index - Supports ADR lifecycle (proposed → accepted → deprecated/superseded) - Categorizes decisions worth recording vs trivial ones to skip - Integrates with planner, code-reviewer, and codebase-onboarding skills Includes Antigravity support via .agents/skills/ and openai.yaml.
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds an Architecture Decision Records (ADR) skill: documentation and an OpenAI agent config defining ADR detection, a three-step ADR workflow (detect → gather context → write/update index), ADR format and indexing rules. Changes are documentation and metadata only; no functional code changes. Changes
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer
participant Agent as ADR Agent
participant Repo as Repository (docs/adr)
participant Index as ADR Index
Dev->>Agent: Make change / raise design question
Agent->>Agent: Detect decision moment (explicit or implicit)
Agent->>Repo: Gather context (files, PR, discussion)
Agent->>Agent: Draft ADR (Context, Decision, Alternatives, Consequences)
Agent->>Repo: Write ADR file to docs/adr
Agent->>Index: Update ADR index entry
Repo->>Dev: ADR created/linked in PR or workspace
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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 |
Contributor
Greptile SummaryThis PR adds an Key changes:
Issues found:
Confidence Score: 3/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Decision Moment Detected] --> B{Explicit or Implicit?}
B -->|Implicit| C[Suggest recording ADR\nWait for user confirmation]
B -->|Explicit| D{docs/adr/ exists?}
C -->|User confirms| D
C -->|User declines| Z[Stop — no files written]
D -->|No - first use| E[Ask user: OK to create\ndocs/adr/ + README + template?]
E -->|User declines| Z
E -->|User confirms| F[Create docs/adr/README.md\n+ template.md]
D -->|Yes| G[Identify decision\n+ gather context]
F --> G
G --> H[Document alternatives\n+ consequences]
H --> I[Assign ADR number\nscan existing + increment]
I --> J[Present draft ADR\nto user for review]
J -->|User approves| K[Write docs/adr/NNNN-title.md\nUpdate README index]
J -->|User declines| L[Discard draft\nREADME + template remain on disk]
style Z fill:#22c55e,color:#fff
style L fill:#f59e0b,color:#fff
style K fill:#3b82f6,color:#fff
Last reviewed commit: 8c33c02 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Comment on lines
+1
to
+6
| --- | ||
| name: architecture-decision-records | ||
| description: Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is. | ||
| origin: ECC | ||
| --- | ||
|
|
Contributor
There was a problem hiding this comment.
AGENTS.md (line 3) currently states "108 skills" and CLAUDE.md lists skills/ — 102 workflow skills. Adding this skill brings the total to at least 109. A recent maintenance commit (fce4513) explicitly synced these counts, so they should be bumped here too to keep the docs accurate.
This is a recurring housekeeping step for skill additions — worth ticking off before merge.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
.agents/skills/architecture-decision-records/SKILL.md (1)
9-34: Add a canonical-reference link to avoid drift.Line 20–Line 27 and Line 31–Line 34 duplicate guidance from the root skill doc in a shorter form. A single pointer to the canonical document will keep cross-harness docs aligned over time.
♻️ Suggested minimal update
# Architecture Decision Records Capture architectural decisions as they happen during coding sessions, producing structured ADR documents that live alongside the code. +Canonical full reference: [`/skills/architecture-decision-records/SKILL.md`](/skills/architecture-decision-records/SKILL.md).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/architecture-decision-records/SKILL.md around lines 9 - 34, The document duplicates guidance already maintained in the root skill doc; remove the redundant short versions under the "When to Activate" and "Key Principles" (and any repeated bullet lists like the brief "Workflow"/"ADR Format" restatement) and replace them with a single canonical-reference link to the root skill document (e.g., "See the canonical ADR guidance in the root skill doc"). Update the text around the headings "When to Activate", "Workflow", "ADR Format", and "Key Principles" to point readers to that canonical document and ensure only unique, file-specific notes remain in SKILL.md.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.agents/skills/architecture-decision-records/SKILL.md:
- Around line 9-34: The document duplicates guidance already maintained in the
root skill doc; remove the redundant short versions under the "When to Activate"
and "Key Principles" (and any repeated bullet lists like the brief
"Workflow"/"ADR Format" restatement) and replace them with a single
canonical-reference link to the root skill document (e.g., "See the canonical
ADR guidance in the root skill doc"). Update the text around the headings "When
to Activate", "Workflow", "ADR Format", and "Key Principles" to point readers to
that canonical document and ensure only unique, file-specific notes remain in
SKILL.md.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 37557ff9-828a-469e-82ec-33ba67aa2208
📒 Files selected for processing (3)
.agents/skills/architecture-decision-records/SKILL.md.agents/skills/architecture-decision-records/agents/openai.yamlskills/architecture-decision-records/SKILL.md
- Add missing "why did we choose X?" read-ADR trigger to .agents/ copy - Add canonical-reference link to .agents/ SKILL.md pointing to full version - Remove integration reference to non-existent codebase-onboarding skill
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/skills/architecture-decision-records/SKILL.md:
- Around line 11-35: The skill markdown currently uses headings like "When to
Activate", "Workflow", "ADR Format", and "Key Principles" but must mirror the
required top-level skill template; update
.agents/skills/architecture-decision-records/SKILL.md to include explicit
top-level sections "When to Use", "How It Works", and "Examples" (you can
move/rename content from "When to Activate" into "When to Use", combine
"Workflow" and "ADR Format" under "How It Works" with the step list and ADR
structure, and include representative usage snippets or sample ADRs under
"Examples"), keep the existing guidance (Context, Decision, Alternatives,
Consequences) and ensure headings are exactly the required titles so the file
matches the skill template.
In `@skills/architecture-decision-records/SKILL.md`:
- Around line 11-107: Rename and/or add the required top-level sections so the
skill uses "When to Use", "How It Works", and "Examples": change the existing
"When to Activate" header to "When to Use", move or retitle "ADR Format" into
"How It Works" (keep the ADR template content under it), and create an
"Examples" section (populate with a brief sample ADR or point to the ADR Index
table). Update any internal references (e.g., "Workflow" can remain but should
be a subsection under "How It Works" or "Examples") so automated parsing expects
those exact header names.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 99fd9420-7677-462a-a565-aaa9087bcfeb
📒 Files selected for processing (2)
.agents/skills/architecture-decision-records/SKILL.mdskills/architecture-decision-records/SKILL.md
Comment on lines
+11
to
+35
| ## When to Activate | ||
|
|
||
| - User says "let's record this decision" or "ADR this" | ||
| - User chooses between significant alternatives (framework, library, pattern, database) | ||
| - User says "we decided to..." or "the reason we're doing X instead of Y is..." | ||
| - User asks "why did we choose X?" (read existing ADRs) | ||
| - During planning phases when architectural trade-offs are discussed | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. **Detect** the decision moment from conversation signals | ||
| 2. **Gather** context, constraints, and alternatives considered | ||
| 3. **Write** a structured ADR to `docs/adr/NNNN-decision-title.md` | ||
| 4. **Update** the ADR index at `docs/adr/README.md` | ||
|
|
||
| ## ADR Format | ||
|
|
||
| Each ADR includes: Context (the problem), Decision (what we chose), Alternatives Considered (with pros/cons/why-not for each), and Consequences (positive, negative, risks). | ||
|
|
||
| ## Key Principles | ||
|
|
||
| - Record the **why**, not just the what | ||
| - Always include rejected alternatives | ||
| - Keep each ADR readable in 2 minutes | ||
| - Superseded decisions link to their replacement |
Contributor
There was a problem hiding this comment.
Mirror required skill sections in the .agents variant too.
Please keep this file’s top-level structure consistent with the required skill template by using explicit When to Use, How It Works, and Examples sections.
As per coding guidelines, “Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/skills/architecture-decision-records/SKILL.md around lines 11 - 35,
The skill markdown currently uses headings like "When to Activate", "Workflow",
"ADR Format", and "Key Principles" but must mirror the required top-level skill
template; update .agents/skills/architecture-decision-records/SKILL.md to
include explicit top-level sections "When to Use", "How It Works", and
"Examples" (you can move/rename content from "When to Activate" into "When to
Use", combine "Workflow" and "ADR Format" under "How It Works" with the step
list and ADR structure, and include representative usage snippets or sample ADRs
under "Examples"), keep the existing guidance (Context, Decision, Alternatives,
Consequences) and ensure headings are exactly the required titles so the file
matches the skill template.
Comment on lines
+11
to
+107
| ## When to Activate | ||
|
|
||
| - User explicitly says "let's record this decision" or "ADR this" | ||
| - User chooses between significant alternatives (framework, library, pattern, database, API design) | ||
| - User says "we decided to..." or "the reason we're doing X instead of Y is..." | ||
| - User asks "why did we choose X?" (read existing ADRs) | ||
| - During planning phases when architectural trade-offs are discussed | ||
|
|
||
| ## ADR Format | ||
|
|
||
| Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development: | ||
|
|
||
| ```markdown | ||
| # ADR-NNNN: [Decision Title] | ||
|
|
||
| **Date**: YYYY-MM-DD | ||
| **Status**: proposed | accepted | deprecated | superseded by ADR-NNNN | ||
| **Deciders**: [who was involved] | ||
|
|
||
| ## Context | ||
|
|
||
| What is the issue that we're seeing that is motivating this decision or change? | ||
|
|
||
| [2-5 sentences describing the situation, constraints, and forces at play] | ||
|
|
||
| ## Decision | ||
|
|
||
| What is the change that we're proposing and/or doing? | ||
|
|
||
| [1-3 sentences stating the decision clearly] | ||
|
|
||
| ## Alternatives Considered | ||
|
|
||
| ### Alternative 1: [Name] | ||
| - **Pros**: [benefits] | ||
| - **Cons**: [drawbacks] | ||
| - **Why not**: [specific reason this was rejected] | ||
|
|
||
| ### Alternative 2: [Name] | ||
| - **Pros**: [benefits] | ||
| - **Cons**: [drawbacks] | ||
| - **Why not**: [specific reason this was rejected] | ||
|
|
||
| ## Consequences | ||
|
|
||
| What becomes easier or more difficult to do because of this change? | ||
|
|
||
| ### Positive | ||
| - [benefit 1] | ||
| - [benefit 2] | ||
|
|
||
| ### Negative | ||
| - [trade-off 1] | ||
| - [trade-off 2] | ||
|
|
||
| ### Risks | ||
| - [risk and mitigation] | ||
| ``` | ||
|
|
||
| ## Workflow | ||
|
|
||
| ### Capturing a New ADR | ||
|
|
||
| When a decision moment is detected: | ||
|
|
||
| 1. **Identify the decision** — extract the core architectural choice being made | ||
| 2. **Gather context** — what problem prompted this? What constraints exist? | ||
| 3. **Document alternatives** — what other options were considered? Why were they rejected? | ||
| 4. **State consequences** — what are the trade-offs? What becomes easier/harder? | ||
| 5. **Assign a number** — scan existing ADRs in `docs/adr/` and increment | ||
| 6. **Write the file** — save to `docs/adr/NNNN-decision-title.md` | ||
| 7. **Update the index** — append to `docs/adr/README.md` | ||
|
|
||
| ### ADR Directory Structure | ||
|
|
||
| ``` | ||
| docs/ | ||
| └── adr/ | ||
| ├── README.md ← index of all ADRs | ||
| ├── 0001-use-nextjs.md | ||
| ├── 0002-postgres-over-mongo.md | ||
| ├── 0003-rest-over-graphql.md | ||
| └── template.md ← blank template for manual use | ||
| ``` | ||
|
|
||
| ### ADR Index Format | ||
|
|
||
| ```markdown | ||
| # Architecture Decision Records | ||
|
|
||
| | ADR | Title | Status | Date | | ||
| |-----|-------|--------|------| | ||
| | [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 | | ||
| | [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 | | ||
| | [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 | | ||
| ``` | ||
|
|
Contributor
There was a problem hiding this comment.
Align section headers with required skill template (When to Use / How It Works / Examples).
This skill is well-structured, but it doesn’t use the required section naming/presence from repo guidelines. Please rename/add explicit sections so automated/consistent parsing stays predictable.
Suggested doc-only adjustment
-## When to Activate
+## When to Use
...
-## Workflow
+## How It Works
...
+## Examples
+
+- **Trigger phrase**: “ADR this decision: REST over GraphQL for public API.”
+- **Expected output**: A new `docs/adr/NNNN-rest-over-graphql.md` entry + README index row.
+- **Read path**: “Why did we choose X?” → locate and summarize matching ADR(s).As per coding guidelines, “Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples.”
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ## When to Activate | |
| - User explicitly says "let's record this decision" or "ADR this" | |
| - User chooses between significant alternatives (framework, library, pattern, database, API design) | |
| - User says "we decided to..." or "the reason we're doing X instead of Y is..." | |
| - User asks "why did we choose X?" (read existing ADRs) | |
| - During planning phases when architectural trade-offs are discussed | |
| ## ADR Format | |
| Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development: | |
| ```markdown | |
| # ADR-NNNN: [Decision Title] | |
| **Date**: YYYY-MM-DD | |
| **Status**: proposed | accepted | deprecated | superseded by ADR-NNNN | |
| **Deciders**: [who was involved] | |
| ## Context | |
| What is the issue that we're seeing that is motivating this decision or change? | |
| [2-5 sentences describing the situation, constraints, and forces at play] | |
| ## Decision | |
| What is the change that we're proposing and/or doing? | |
| [1-3 sentences stating the decision clearly] | |
| ## Alternatives Considered | |
| ### Alternative 1: [Name] | |
| - **Pros**: [benefits] | |
| - **Cons**: [drawbacks] | |
| - **Why not**: [specific reason this was rejected] | |
| ### Alternative 2: [Name] | |
| - **Pros**: [benefits] | |
| - **Cons**: [drawbacks] | |
| - **Why not**: [specific reason this was rejected] | |
| ## Consequences | |
| What becomes easier or more difficult to do because of this change? | |
| ### Positive | |
| - [benefit 1] | |
| - [benefit 2] | |
| ### Negative | |
| - [trade-off 1] | |
| - [trade-off 2] | |
| ### Risks | |
| - [risk and mitigation] | |
| ``` | |
| ## Workflow | |
| ### Capturing a New ADR | |
| When a decision moment is detected: | |
| 1. **Identify the decision** — extract the core architectural choice being made | |
| 2. **Gather context** — what problem prompted this? What constraints exist? | |
| 3. **Document alternatives** — what other options were considered? Why were they rejected? | |
| 4. **State consequences** — what are the trade-offs? What becomes easier/harder? | |
| 5. **Assign a number** — scan existing ADRs in `docs/adr/` and increment | |
| 6. **Write the file** — save to `docs/adr/NNNN-decision-title.md` | |
| 7. **Update the index** — append to `docs/adr/README.md` | |
| ### ADR Directory Structure | |
| ``` | |
| docs/ | |
| └── adr/ | |
| ├── README.md ← index of all ADRs | |
| ├── 0001-use-nextjs.md | |
| ├── 0002-postgres-over-mongo.md | |
| ├── 0003-rest-over-graphql.md | |
| └── template.md ← blank template for manual use | |
| ``` | |
| ### ADR Index Format | |
| ```markdown | |
| # Architecture Decision Records | |
| | ADR | Title | Status | Date | | |
| |-----|-------|--------|------| | |
| | [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 | | |
| | [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 | | |
| | [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 | | |
| ``` | |
| ## When to Use | |
| - User explicitly says "let's record this decision" or "ADR this" | |
| - User chooses between significant alternatives (framework, library, pattern, database, API design) | |
| - User says "we decided to..." or "the reason we're doing X instead of Y is..." | |
| - User asks "why did we choose X?" (read existing ADRs) | |
| - During planning phases when architectural trade-offs are discussed | |
| ## ADR Format | |
| Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development: | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/architecture-decision-records/SKILL.md` around lines 11 - 107, Rename
and/or add the required top-level sections so the skill uses "When to Use", "How
It Works", and "Examples": change the existing "When to Activate" header to
"When to Use", move or retitle "ADR Format" into "How It Works" (keep the ADR
template content under it), and create an "Examples" section (populate with a
brief sample ADR or point to the ADR Index table). Update any internal
references (e.g., "Workflow" can remain but should be a subsection under "How It
Works" or "Examples") so automated parsing expects those exact header names.
- Add Step 1 to workflow: initialize docs/adr/ directory, README.md index, and template.md on first use when directory doesn't exist - Add "API design" to .agents/ alternatives trigger to match canonical version
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
skills/architecture-decision-records/SKILL.md (1)
11-171:⚠️ Potential issue | 🟡 MinorUse the required skill section headers exactly (
When to Use/How It Works/Examples).Line 11 currently uses
## When to Activate, and the document does not expose the exact required top-level trio. Please retitle/restructure so parsers can reliably detect those sections (e.g., moveADR Format/WorkflowunderHow It Works, and add a dedicatedExamplesheading).As per coding guidelines, “Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/architecture-decision-records/SKILL.md` around lines 11 - 171, Rename the top-level header "## When to Activate" to exactly "## When to Use"; create a new top-level header "## How It Works" and move the existing "## ADR Format", "## Workflow" (including "### Capturing a New ADR", "### ADR Directory Structure", and "### ADR Index Format"), and related procedural content under that "How It Works" section; add a new top-level header "## Examples" and populate it with one or two short example ADRs or links (you can reuse the ADR index table as example content); ensure the document now has the exact trio of top-level headers "When to Use", "How It Works", and "Examples" so parsers can detect them reliably and keep all existing content unchanged except for re-titling and moving sections.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@skills/architecture-decision-records/SKILL.md`:
- Around line 11-171: Rename the top-level header "## When to Activate" to
exactly "## When to Use"; create a new top-level header "## How It Works" and
move the existing "## ADR Format", "## Workflow" (including "### Capturing a New
ADR", "### ADR Directory Structure", and "### ADR Index Format"), and related
procedural content under that "How It Works" section; add a new top-level header
"## Examples" and populate it with one or two short example ADRs or links (you
can reuse the ADR index table as example content); ensure the document now has
the exact trio of top-level headers "When to Use", "How It Works", and
"Examples" so parsers can detect them reliably and keep all existing content
unchanged except for re-titling and moving sections.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b10d78a4-2a75-42ff-8a92-4b20cd9376cf
📒 Files selected for processing (2)
.agents/skills/architecture-decision-records/SKILL.mdskills/architecture-decision-records/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .agents/skills/architecture-decision-records/SKILL.md
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
1 issue found across 2 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="skills/architecture-decision-records/SKILL.md">
<violation number="1" location="skills/architecture-decision-records/SKILL.md:76">
P2: First-time initialization creates an empty ADR index even though later steps assume a preformatted index table, causing malformed `docs/adr/README.md` on the first ADR.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
- Init step: seed README.md with index table header so Step 8 can
append rows correctly on first ADR
- Add read-path workflow: graceful handling when docs/adr/ is empty
or absent ("No ADRs found, would you like to start?")
- Implicit signals: add "do not auto-create without user confirmation"
guard, tighten triggers to require conclusion/rationale not just
discussion, remove overly broad "testing strategy" trigger
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
skills/architecture-decision-records/SKILL.md (1)
11-179:⚠️ Potential issue | 🟡 MinorSection headers still don't match required skill template.
The previous review comment flagged this issue, but it remains unresolved. The skill must use the exact section headers required by the repository guidelines:
- Line 11: "When to Activate" should be "When to Use"
- Lines 19-116: "ADR Format" and "Workflow" should be consolidated or reorganized under "How It Works"
- Missing: An "Examples" section with concrete trigger phrases, expected outputs, or sample ADRs
As per coding guidelines, "Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples."
📋 Suggested restructuring
Rename the main sections to match the required template:
-## When to Activate +## When to Use - User explicitly says "let's record this decision" or "ADR this" ... -## ADR Format - -Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development: -... - -## Workflow +## How It Works +### ADR Format + +Use the lightweight ADR format proposed by Michael Nygard, adapted for AI-assisted development: +... + +### Workflow ### Capturing a New ADR ... + +## Examples + +### Example 1: Explicit ADR Request +**Trigger**: "ADR this decision: use PostgreSQL over MongoDB for primary datastore" +**Output**: Creates `docs/adr/0001-postgres-over-mongo.md` and updates the README index. + +### Example 2: Reading Existing ADRs +**Trigger**: "Why did we choose Next.js?" +**Output**: Locates and summarizes ADR-0001 Context and Decision sections. + +### Example 3: Implicit Detection +**Trigger**: "After comparing REST and GraphQL, REST is simpler for our public API use case." +**Output**: Suggests: "This sounds like an architectural decision. Would you like me to create an ADR?"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/architecture-decision-records/SKILL.md` around lines 11 - 179, Rename the "When to Activate" header to the exact required "When to Use", consolidate the "ADR Format" and "Workflow" content under a single "How It Works" header (reorganize subsections like "Capturing a New ADR", "Reading Existing ADRs", and "ADR Directory Structure" beneath it), and add a new "Examples" section containing concrete trigger phrases, expected outputs, and at least one sample ADR (use the existing ADR template block as a sample). Update any internal references to the old header names to the new ones to keep the skill compliant with the repository's "When to Use / How It Works / Examples" template.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@skills/architecture-decision-records/SKILL.md`:
- Around line 11-179: Rename the "When to Activate" header to the exact required
"When to Use", consolidate the "ADR Format" and "Workflow" content under a
single "How It Works" header (reorganize subsections like "Capturing a New ADR",
"Reading Existing ADRs", and "ADR Directory Structure" beneath it), and add a
new "Examples" section containing concrete trigger phrases, expected outputs,
and at least one sample ADR (use the existing ADR template block as a sample).
Update any internal references to the old header names to the new ones to keep
the skill compliant with the repository's "When to Use / How It Works /
Examples" template.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a93b7ee0-ab64-4072-93d1-6e316e41e679
📒 Files selected for processing (1)
skills/architecture-decision-records/SKILL.md
Contributor
There was a problem hiding this comment.
3 issues found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="skills/architecture-decision-records/SKILL.md">
<violation number="1" location="skills/architecture-decision-records/SKILL.md:90">
P2: ADR lookup is brittle because it relies only on the README index and can miss existing ADR files when the index is stale or incomplete.</violation>
<violation number="2" location="skills/architecture-decision-records/SKILL.md:91">
P2: The “why did we choose X?” read flow omits rationale-heavy ADR sections, so responses can be incomplete or misleading.</violation>
<violation number="3" location="skills/architecture-decision-records/SKILL.md:128">
P2: Instruction conflict: implicit signals forbid auto-creation, but the decision-moment workflow still writes ADR files immediately without a confirmation gate.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| When a user asks "why did we choose X?": | ||
|
|
||
| 1. Check if `docs/adr/` exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?" | ||
| 2. If it exists, scan `docs/adr/README.md` index for relevant entries |
Contributor
There was a problem hiding this comment.
P2: ADR lookup is brittle because it relies only on the README index and can miss existing ADR files when the index is stale or incomplete.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/architecture-decision-records/SKILL.md, line 90:
<comment>ADR lookup is brittle because it relies only on the README index and can miss existing ADR files when the index is stale or incomplete.</comment>
<file context>
@@ -82,6 +82,15 @@ When a decision moment is detected:
+When a user asks "why did we choose X?":
+
+1. Check if `docs/adr/` exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?"
+2. If it exists, scan `docs/adr/README.md` index for relevant entries
+3. Read matching ADR files and present the Context and Decision sections
+4. If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"
</file context>
Suggested change
| 2. If it exists, scan `docs/adr/README.md` index for relevant entries | |
| 2. If it exists, scan `docs/adr/README.md` index for relevant entries; if the index is missing, unreadable, or has no match, fall back to scanning `docs/adr/*.md` (excluding `template.md`) for likely matches |
|
|
||
| 1. Check if `docs/adr/` exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?" | ||
| 2. If it exists, scan `docs/adr/README.md` index for relevant entries | ||
| 3. Read matching ADR files and present the Context and Decision sections |
Contributor
There was a problem hiding this comment.
P2: The “why did we choose X?” read flow omits rationale-heavy ADR sections, so responses can be incomplete or misleading.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/architecture-decision-records/SKILL.md, line 91:
<comment>The “why did we choose X?” read flow omits rationale-heavy ADR sections, so responses can be incomplete or misleading.</comment>
<file context>
@@ -82,6 +82,15 @@ When a decision moment is detected:
+
+1. Check if `docs/adr/` exists — if not, respond: "No ADRs found in this project. Would you like to start recording architectural decisions?"
+2. If it exists, scan `docs/adr/README.md` index for relevant entries
+3. Read matching ADR files and present the Context and Decision sections
+4. If no match is found, respond: "No ADR found for that decision. Would you like to record one now?"
+
</file context>
Suggested change
| 3. Read matching ADR files and present the Context and Decision sections | |
| 3. Read matching ADR files and present the Context, Decision, Alternatives Considered, and Consequences sections (summarizing the rationale and trade-offs). |
- Canonical SKILL.md: init step now asks user before creating docs/adr/ - .agents/ condensed version: add confirmation gate for implicit signals and explicit consent step before any file writes
Comment on lines
+19
to
+25
| ## Workflow | ||
|
|
||
| 1. **Detect** the decision moment from conversation signals — for implicit signals, **suggest** recording an ADR and wait for user confirmation before proceeding | ||
| 2. **Confirm** with the user before creating any files (especially `docs/adr/` on first use) | ||
| 3. **Gather** context, constraints, and alternatives considered | ||
| 4. **Write** a structured ADR to `docs/adr/NNNN-decision-title.md` | ||
| 5. **Update** the ADR index at `docs/adr/README.md` |
Contributor
There was a problem hiding this comment.
The "When to Activate" list includes User asks "why did we choose X?" (read existing ADRs) at line 16, but the 5-step Workflow below is exclusively a capture/write flow (Gather → Write → Update). When this read trigger fires, the model following this condensed workflow has no instruction to branch into a read-only path — it will proceed into steps 3–5 which attempt to write new ADR files, which is incorrect behavior for a lookup query.
The full skills/architecture-decision-records/SKILL.md has a dedicated "Reading Existing ADRs" sub-workflow (lines 85–92) that handles this case properly. This condensed version — used by the Antigravity/Codex harness — needs the same branching instruction. Consider adding a brief note like:
> **Read path**: If the trigger is "why did we choose X?", skip to checking `docs/adr/README.md` for matching entries and present the relevant ADR — do not proceed to steps 3–5.| ```markdown | ||
| # ADR-NNNN: [Decision Title] | ||
|
|
||
| **Date**: YYYY-MM-DD |
Contributor
There was a problem hiding this comment.
The ADR template requires **Date**: YYYY-MM-DD, but Claude has no inherent access to the current date — it must come from the session's system context (which isn't always present). Without an instruction, Claude may silently populate this field with a hallucinated or training-data-era date, producing ADRs with incorrect timestamps.
Consider adding a note in the template or workflow, for example:
**Date**: YYYY-MM-DD ← use today's date from session context; if unavailable, ask the userOr add a step to the capture workflow:
0. **Determine the date** — use the date from the system context if available; otherwise ask the user: "What is today's date for the ADR record?"
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (4)
skills/architecture-decision-records/SKILL.md (4)
11-11:⚠️ Potential issue | 🟡 MinorRename section header to "When to Use" per repository guidelines.
The section is currently titled "When to Activate" but should be "When to Use" to match the required skill template format.
As per coding guidelines, "Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/architecture-decision-records/SKILL.md` at line 11, Rename the section header "## When to Activate" to "## When to Use" in SKILL.md to conform to the repository skill template; locate the existing header string "When to Activate" (exact match) and replace it with "When to Use", then verify surrounding sections include "How It Works" and "Examples" headings per guidelines.
19-68: 🛠️ Refactor suggestion | 🟠 MajorReorganize "ADR Format" as a subsection under "How It Works".
This section contains excellent content but should be nested under a top-level "How It Works" section rather than being a standalone top-level section.
As per coding guidelines, "Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/architecture-decision-records/SKILL.md` around lines 19 - 68, Move the current "ADR Format" top-level section into a subsection under the existing "How It Works" heading and ensure the document has the three required top-level sections: "When to Use", "How It Works", and "Examples"; specifically, rename or indent "## ADR Format" so it becomes a third-level or nested heading under "## How It Works" (e.g., "### ADR Format") and adjust surrounding TOC/ordering so "When to Use" remains the first top-level section, "How It Works" contains the ADR content, and "Examples" follows as a top-level section.
1-179:⚠️ Potential issue | 🟡 MinorAdd required "Examples" section.
The skill documentation is missing the required "Examples" section. This section should demonstrate concrete usage scenarios with trigger phrases and expected outputs.
📝 Suggested Examples section
Add this section after line 179:
## Examples ### Example 1: Explicit ADR Request **Trigger**: "ADR this decision: we're using REST over GraphQL for the public API" **Expected output**: - Creates `docs/adr/0001-rest-over-graphql.md` with full ADR structure - Updates `docs/adr/README.md` index with new entry - Confirms: "ADR-0001 created and indexed" ### Example 2: Reading Existing ADRs **Trigger**: "Why did we choose PostgreSQL?" **Expected output**: - Searches `docs/adr/README.md` for PostgreSQL-related entries - Reads matching ADR file(s) - Presents Context and Decision sections from ADR-0002 ### Example 3: Implicit Decision Detection **Trigger**: "After comparing Next.js and Remix, Next.js fits better because of our Vercel deployment" **Expected output**: - Detects architectural decision signal - Responds: "This sounds like an architectural decision. Would you like me to record this as an ADR?" - Waits for user confirmation before creating filesAs per coding guidelines, "Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/architecture-decision-records/SKILL.md` around lines 1 - 179, The skill is missing the required "Examples" section; add a new "## Examples" section to SKILL.md under the Architecture Decision Records skill that includes concrete trigger phrases and expected outputs (e.g., the three suggested examples: Explicit ADR Request, Reading Existing ADRs, Implicit Decision Detection), showing exact triggers and the resulting actions (creating docs/adr/NNNN-*.md, updating README index, reading ADRs, or prompting for confirmation). Place this Examples section after the existing content so it appears with the other top-level headings, match the markdown style used elsewhere, and ensure each example includes a short Trigger and Expected output description to meet the "When to Use / How It Works / Examples" guideline.
70-116: 🛠️ Refactor suggestion | 🟠 MajorReorganize "Workflow" as a subsection under "How It Works".
The workflow content is comprehensive and well-structured, but it should be nested under a top-level "How It Works" section rather than being standalone.
As per coding guidelines, "Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/architecture-decision-records/SKILL.md` around lines 70 - 116, Move the current top-level "Workflow" section into the "How It Works" section as a subsection: rename the "## Workflow" heading to "### Workflow" (or nest it under an existing "## How It Works" heading), keeping all its numbered lists, ADR Directory Structure, and ADR Index Format content intact; if "How It Works" does not exist, add a "## How It Works" header above the relocated content and ensure the SKILL.md file now contains the required top-level sections "When to Use", "How It Works", and "Examples".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/architecture-decision-records/SKILL.md`:
- Around line 176-179: Update the ADR doc claims about Planner and Code Reviewer
agent integrations: either remove the two bullet points under "Integration with
Other Skills" that state the Planner agent "suggests creating an ADR" and the
Code Reviewer agent "flags PRs without a corresponding ADR", or implement the
integrations in the respective agents; if removing, mark them as "planned
enhancements" in SKILL.md instead of asserting they exist; if implementing, add
the actual logic in the Planner agent (where proposals are generated, e.g., the
function/module that creates architecture suggestions) to call an ADR creation
helper, and add a check in the Code Reviewer agent (the PR linting/analysis
routine) to detect architectural changes and verify an ADR exists, then update
SKILL.md to accurately reflect the new behavior.
---
Duplicate comments:
In `@skills/architecture-decision-records/SKILL.md`:
- Line 11: Rename the section header "## When to Activate" to "## When to Use"
in SKILL.md to conform to the repository skill template; locate the existing
header string "When to Activate" (exact match) and replace it with "When to
Use", then verify surrounding sections include "How It Works" and "Examples"
headings per guidelines.
- Around line 19-68: Move the current "ADR Format" top-level section into a
subsection under the existing "How It Works" heading and ensure the document has
the three required top-level sections: "When to Use", "How It Works", and
"Examples"; specifically, rename or indent "## ADR Format" so it becomes a
third-level or nested heading under "## How It Works" (e.g., "### ADR Format")
and adjust surrounding TOC/ordering so "When to Use" remains the first top-level
section, "How It Works" contains the ADR content, and "Examples" follows as a
top-level section.
- Around line 1-179: The skill is missing the required "Examples" section; add a
new "## Examples" section to SKILL.md under the Architecture Decision Records
skill that includes concrete trigger phrases and expected outputs (e.g., the
three suggested examples: Explicit ADR Request, Reading Existing ADRs, Implicit
Decision Detection), showing exact triggers and the resulting actions (creating
docs/adr/NNNN-*.md, updating README index, reading ADRs, or prompting for
confirmation). Place this Examples section after the existing content so it
appears with the other top-level headings, match the markdown style used
elsewhere, and ensure each example includes a short Trigger and Expected output
description to meet the "When to Use / How It Works / Examples" guideline.
- Around line 70-116: Move the current top-level "Workflow" section into the
"How It Works" section as a subsection: rename the "## Workflow" heading to "###
Workflow" (or nest it under an existing "## How It Works" heading), keeping all
its numbered lists, ADR Directory Structure, and ADR Index Format content
intact; if "How It Works" does not exist, add a "## How It Works" header above
the relocated content and ensure the SKILL.md file now contains the required
top-level sections "When to Use", "How It Works", and "Examples".
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 93e8475b-77a5-4bce-b337-a05720edb03a
📒 Files selected for processing (2)
.agents/skills/architecture-decision-records/SKILL.mdskills/architecture-decision-records/SKILL.md
✅ Files skipped from review due to trivial changes (1)
- .agents/skills/architecture-decision-records/SKILL.md
Comment on lines
+176
to
+179
| ## Integration with Other Skills | ||
|
|
||
| - **Planner agent**: when the planner proposes architecture changes, suggest creating an ADR | ||
| - **Code reviewer agent**: flag PRs that introduce architectural changes without a corresponding ADR |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Search for ADR-related logic in planner and code-reviewer agent files
echo "=== Searching planner.md for ADR references ==="
rg -n -C3 -i 'adr|architecture.decision' agents/planner.md || echo "No ADR references found in planner.md"
echo -e "\n=== Searching code-reviewer.md for ADR references ==="
rg -n -C3 -i 'adr|architecture.decision' agents/code-reviewer.md || echo "No ADR references found in code-reviewer.md"
echo -e "\n=== Checking if ADR skill is referenced in agent configs ==="
fd -e md -e yaml . agents/ --exec rg -l 'architecture-decision-records'Repository: affaan-m/everything-claude-code
Length of output: 321
Remove or implement claimed ADR integrations with Planner and Code Reviewer agents.
Lines 176-179 claim the Planner agent should "suggest creating an ADR" and the Code Reviewer agent should "flag PRs that introduce architectural changes without a corresponding ADR." Neither integration exists in the actual agent implementations.
Either remove these claims and document them as planned enhancements, or update the agent files to implement the integrations.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/architecture-decision-records/SKILL.md` around lines 176 - 179, Update
the ADR doc claims about Planner and Code Reviewer agent integrations: either
remove the two bullet points under "Integration with Other Skills" that state
the Planner agent "suggests creating an ADR" and the Code Reviewer agent "flags
PRs without a corresponding ADR", or implement the integrations in the
respective agents; if removing, mark them as "planned enhancements" in SKILL.md
instead of asserting they exist; if implementing, add the actual logic in the
Planner agent (where proposals are generated, e.g., the function/module that
creates architecture suggestions) to call an ADR creation helper, and add a
check in the Code Reviewer agent (the PR linting/analysis routine) to detect
architectural changes and verify an ADR exists, then update SKILL.md to
accurately reflect the new behavior.
Contributor
There was a problem hiding this comment.
1 issue found across 2 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="skills/architecture-decision-records/SKILL.md">
<violation number="1" location="skills/architecture-decision-records/SKILL.md:76">
P2: Consent gating is inconsistent: confirmation is required for initialization, but ADR file creation remains unconditional and lacks an explicit refusal/stop path.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="skills/architecture-decision-records/SKILL.md">
<violation number="1" location="skills/architecture-decision-records/SKILL.md:82">
P2: ADR number selection can become stale because numbering occurs before a user-review pause and is not revalidated right before file write.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| 4. **Document alternatives** — what other options were considered? Why were they rejected? | ||
| 5. **State consequences** — what are the trade-offs? What becomes easier/harder? | ||
| 6. **Assign a number** — scan existing ADRs in `docs/adr/` and increment | ||
| 7. **Confirm and write** — present the draft ADR to the user for review. Only write to `docs/adr/NNNN-decision-title.md` after explicit approval. If the user declines, discard the draft without writing any files. |
Contributor
There was a problem hiding this comment.
P2: ADR number selection can become stale because numbering occurs before a user-review pause and is not revalidated right before file write.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/architecture-decision-records/SKILL.md, line 82:
<comment>ADR number selection can become stale because numbering occurs before a user-review pause and is not revalidated right before file write.</comment>
<file context>
@@ -79,7 +79,7 @@ When a decision moment is detected:
5. **State consequences** — what are the trade-offs? What becomes easier/harder?
6. **Assign a number** — scan existing ADRs in `docs/adr/` and increment
-7. **Write the file** — save to `docs/adr/NNNN-decision-title.md`
+7. **Confirm and write** — present the draft ADR to the user for review. Only write to `docs/adr/NNNN-decision-title.md` after explicit approval. If the user declines, discard the draft without writing any files.
8. **Update the index** — append to `docs/adr/README.md`
</file context>
Suggested change
| 7. **Confirm and write** — present the draft ADR to the user for review. Only write to `docs/adr/NNNN-decision-title.md` after explicit approval. If the user declines, discard the draft without writing any files. | |
| 7. **Confirm and write** — present the draft ADR to the user for review. Before writing, re-scan `docs/adr/` and confirm `NNNN` is still the next available number (and update filename/index entry if needed). Only write to `docs/adr/NNNN-decision-title.md` after explicit approval. If the user declines, discard the draft without writing any files. |
Author
|
@affaan-m Ready for review — all bot feedback has been addressed. |
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
Adds an
architecture-decision-recordsskill that captures architectural decisions made during Claude Code sessions as structured ADR documents.Motivation
Architectural decisions typically live in Slack threads, PR comments, or someone's memory — and are lost within weeks. This skill turns "we decided to use X because Y" moments into durable, searchable records that live alongside the code.
What It Does
docs/adr/with a README indexKey Design Decisions
Type
Testing
openai.yamlfollowing existing patternChecklist
Summary by cubic
Adds an
architecture-decision-recordsskill to capture architectural decisions as numbered ADRs indocs/adr/with an index and lifecycle. Initializes the ADR folder on first use (seeded index + template) and writes files only after explicit user approval; can read ADRs to answer “why did we choose X?”.New Features
allow_implicit_invocationvia.agents/skills/architecture-decision-records/agents/openai.yaml.Bug Fixes
docs/adr/README.md(seeded index) andtemplate.mdon first use; handle empty/absent ADRs with a friendly prompt..agentstriggers (added API design and read-ADR), linked.agents/SKILL.mdto the canonical reference, and removed the non-existentcodebase-onboardingintegration.Written for commit 8c33c02. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation