adr

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# ADR

Architectural Decision Records — minimal, dated, sequentially numbered. The point is recording **that** a decision was made and **why**, not filling out template sections.

Pattern adapted from `mattpocock/skills` (`grill-with-docs/ADR-FORMAT.md`).

## Step 0 — Resolve company + scope

`$ARGUMENTS` may include:

- `[company]` slug — fall back to manifest / handoff / cwd inference if absent
- `[repo|hq]` scope — pick home directory
- `<one-line decision summary>` — used as title and slug seed

If scope is ambiguous, ask via `AskUserQuestion`:

| Choice | Home | When |
|---|---|---|
| `repo` | `<repo>/docs/adr/` | Decision is bound to specific code; reviewers will read it alongside the code |
| `hq` | `companies/{co}/knowledge/adrs/` | Decision is org-level (e.g. "we use Linear, not Jira"; "all auth via Cognito") |

If no company resolves and scope is `hq`, default to `core/knowledge/public/adrs/` (rare — most ADRs have a tenant).

## Step 1 — Three-condition gate (HARD BLOCK)

Ask the user three yes/no questions via a single `AskUserQuestion` call:

1. **Hard to reverse** — would changing your mind later cost meaningful effort? (refactor, migration, contract renegotiation)
2. **Surprising without context** — would a future reader look at the result and wonder "why on earth did they do it this way?"
3. **Result of a real trade-off** — were there genuine alternatives, and did you pick this one for specific reasons?

If **any** answer is no → DO NOT WRITE THE ADR. Offer alternatives:

| Failed condition | Alternative |
|---|---|
| Easy to reverse | Skip — you'll just reverse it later |
| Not surprising | Skip — nobody will wonder |
| No real trade-off | Add to `GLOSSARY.md` glossary instead, or skip |

Re-prompt: "Skip ADR / Add to GLOSSARY.md / Force-write anyway (rarely correct)". Only `Force-write` proceeds; record reasoning in the ADR body so the override is explicit.

## Step 2 — Locate or create target directory

```bash
# repo scope
mkdir -p <repo>/docs/adr/

# hq scope
mkdir -p companies/{co}/knowledge/adrs/
```

Lazy-create only when the first ADR is needed.

## Step 3 — Compute next number

```bash
ls <target>/[0-9][0-9][0-9][0-9]-*.md 2>/dev/null \
  | sed 's|.*/\([0-9]*\)-.*|\1|' \
  | sort -n \
  | tail -1
```

Increment by 1. Default to `0001` if no existing ADRs. Format: `NNNN` (4-digit zero-padded).

Slug from the user's title:

- Lowercase
- Spaces / underscores → `-`
- Strip non-alphanumeric except `-`
- Cap at 60 chars

Final filename: `NNNN-slug.md`

## Step 4 — Walk the user through 1–3 sentences

Single `AskUserQuestion` (or sequential prompts) collecting:

- **Title** — short noun phrase, sentence case, ≤60 chars
- **Body** — 1–3 sentences answering: what's the context, what did we decide, why this over alternatives

That's the minimum. The value is in *recording* the decision, not in completing a template.

## Step 5 — Optional sections (offer, don't force)

Ask via `AskUserQuestion` (multiSelect) which (if any) to include:

- **Status frontmatter** (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are likely to be revisited
- **Considered Options** — only when rejected alternatives are worth remembering
- **Consequences** — only when non-obvious downstream effects need calling out

If user picks none, the ADR is just title + 1–3 sentences. Good.

## Step 6 — Write ADR

Template (use only the sections selected in Step 5):

```markdown
---
status: <accepted|proposed|...>          # only if Status was selected
date: <YYYY-MM-DD>
related: []                              # ADR numbers, optional
---

# <Title>

<1-3 sentences: context, decision, why.>

## Considered Options                    <!-- optional -->

- <Option A> — <why rejected>
- <Option B> — <why rejected>

## Consequences                          <!-- optional -->

- <non-obvious downstream effect>
```

## Step 7 — Cross-link

From indigoai-us/hq-pack-core-skills, MIT.

More from indigoai-us/hq-pack-core-skills