adr

Files (2)

• SKILL.md
• adr-format.md · references/

SKILL.md (first lines)

# ABOUTME: Full ADR lifecycle: Linear ticket, branch, write, vault, review, commit, PR
# ABOUTME: Follows HikmaAI format and ADR guidelines (Linear ticket = ADR number)

# Architecture Decision Records

## Quality Notes

- ADRs are permanent records; accuracy matters more than speed
- Every claim should be backed by evidence (code, docs, benchmarks)
- Do not skip the refinement step for ambiguous topics

## Workflow

### Step 1: Refine Requirements

Before writing, clarify scope using `AskUserQuestion`:

- What decision is being made? (single clear question)
- What options are on the table?
- What constraints apply?
- Who are the stakeholders?

Skip if user provided a fully specified request or said "just write it."

### Step 2: Research

Launch `research-analyst` agent to gather:

- Prior art (existing ADRs in vault, LEARNING.md, MEMORY.md)
- External references (competing approaches, industry patterns)
- Current codebase state (relevant files, existing patterns)

For HikmaAI projects, always check:
- Vault: `Projects/HikmaAI/HLD/` for existing ADRs
- CLAUDE.md for architecture context
- Relevant source code for current implementation

### Step 3: Create Linear Ticket (reserves the ADR number)

**The Linear ticket number IS the ADR number.** No separate counter. Gaps in numbering are expected.

Before calling any `mcp__linear-server__*` tool (here and in Step 10), verify it exists in the current session; MCP tool names change, so fall back to the Linear web UI if it is absent.

```
mcp__linear-server__save_issue:
  title: "ADR: {Decision Title}"
  team: "Hikmaai"
  project: "ADR Lifecycle"
  state: "In Progress"
  assignee: "me"
  priority: 2  (or as appropriate)
  description: "One-line summary.\n\nRepo: hikma-system-design\nBranch: adr/{NNN}-{kebab-title}"
```

Note the ticket identifier (e.g., `HIK-249`): the numeric part (249) is the ADR number.

### Step 4: Create Branch

```bash
cd ~/Development/hikmaAI/hikma-system-design
git checkout -b adr/{NNN}-{kebab-title} main
```

Example: `adr/249-mirsad-cryptographic-decision-trail`

### Step 5: Write the ADR

1. Copy `adr/TEMPLATE.md` to `adr/ADR-{NNN}-{kebab-title}.md`
2. Fill in all sections following the template guidance
3. Set frontmatter fields:
   - `**Status:** Drafting`
   - `**Linear:** [HIK-{NNN}](https://linear.app/hikmaai/issue/HIK-{NNN})`
   - `**Obsidian:** [[{NNN}-{kebab-title}]]`

Follow the HikmaAI ADR format exactly (full section-by-section template in `references/adr-format.md`).

### Step 6: Update README.md

Add a row to the ADR Index table in `hikma-system-design/README.md`:

```markdown
| {NNN} | {project} | {Title} | Drafting |
```

If the README's Conventions section gives an ADR filename pattern other than `ADR-NNN-kebab-title.md`, update it to match.

### Step 7: Store in Vault

Save using the `obsidian` skill:

```bash
obsidian create name="Projects/HikmaAI/HLD/ADR-{NNN}-{Title}" content="..." silent
```

**Fallback** (direct file access):
Write to `/Users/maroffo/Library/Mobile Documents/iCloud~md~obsidian/Documents/Projects/HikmaAI/HLD/ADR-{NNN}-{Title}.md`

### Step 8: Review

Run `dx-reviewer` agent on the ADR file, focusing on:

- Completeness (all sections present)
- Clarity (decisions unambiguous)
- Evidence (claims backed by data/code)
- Actionability (enough detail to implement)

This launch cannot pass `isolation: "worktree"`: the ADR file is still uncommitted here (Step 9 commits it), and a reviewer worktree materialises at the default branch, where the file does not exist. Open the brief with the first line `ISOLATION-EXEMPT: ADR review, the target file is uncommitted and the reviewer only reads it`, which is what `reviewer-isolation-guard` reads; the reviewer then stays read-only agent-side, which is all this step wants.

Alternatively, if the ADR is short and straightforward, skip the agent and self-review against the checklist above.

### Step 9: Commit, Push, PR

**Commit:**
```bash
git add adr/ADR-{NNN}-{kebab-title}.md README.md [any other changed files]
git commit -m "docs: ADR-{NNN} {Title} (HIK-{NNN})

{One-line summary of the decision.}

From maroffo/claude-forge, MIT.

More from maroffo/claude-forge