--- name: adr-author description: Create Architecture Decision Records (ADRs) for architecturally significant design decisions. Invoke when the user explicitly requests planning/design work ("let's plan X", "decide Y vs Z", "design the W module", "create an ADR for ..."), OR when the conversation drifts into architecturally significant territory and you proactively flag it (user must confirm — never auto-invoke). Handles two paradigms: per-repo `docs/adr/NNNN-.md` files (Nygard style, product/code decisions) and the workspace-level `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` table row (LLMP-DEC-N, protocol-meta decisions). Structured interview: context → alternatives → trade-offs → decision → consequences. Always produces a durable `.md` artifact, never just a conversational answer. compatibility: Designed for Claude Code and GitHub Copilot (VS). Uses the host agent's Read/Write/Edit/Glob/Grep tools. metadata: author: Fullepi --- # adr-author Structured interview-style skill that captures architecturally significant decisions as Architecture Decision Records. The output is a durable artifact (a new `.md` file or a new table row) — the decision, its context, the alternatives considered, and its consequences remain accessible months or years later. Without this skill, design rationale tends to disappear into chat history or get flattened into TODO entries that lose the "why". ## When to invoke ### Explicit ADR invocation (auto-trigger — no ask-back) User message contains the literal keyword **"ADR"** or **"Architecture Decision Record"** (case-insensitive, any language): - "create an ADR for X", "write a decision record about Y" - "csináljunk egy ADR-t Z-re", "ez ADR-érdemes" - "this is ADR-worthy" → **Invoke directly**, proceed to Step 1. Skip the complexity sniff. The user has explicitly named the formal mode. ### Implicit planning request (ASK BACK first if complex) User uses planning/design language **WITHOUT** the "ADR" keyword: - "tervezzük meg X", "let's plan X" - "design the W module" - "döntsük el Y vagy Z", "decide between Y and Z" - "válasszunk approach-ot V-re", "choose an approach to V" - "milyen megközelítés", "what's our approach to W" → Apply the **complexity sniff** below. If ANY one heuristic fires, **ask back** — do not auto-invoke. If none fires, the request is treated as conversational planning (structured response, but no ADR file). **Complexity sniff** (any single one is enough to trigger the ask): - **Cross-cutting** — touches ≥ 2 topics (LOG + SIG, BIN + TOON, etc.) - **Cross-repo** — touches ≥ 2 repos (especially framework↔consumer boundary) - **Reversibility low** — DB schema change, public API shape, breaking change, deployment-affecting - **≥ 2 valid alternative approaches** mentioned or implied - **Vocabulary signals**: "design", "approach", "strategy", "decide between", "choose", "alternatives" (vs. "tweak", "rename", "fix") - **Re-openable question** — something someone might reasonably re-open in 6-18 months asking "wait, why did we pick this?" - **New public-facing API** shape being shaped **Ask-back template** (LLM emits this; waits for user response BEFORE invoking): > "Ez ADR-érdemesnek tűnik mert {concrete heuristic 1, heuristic 2 — name them}. Akarsz formális ADR-t (`adr-author` skill: kontextus → alternatívák → trade-offs → döntés → következmények, durable `.md` artifact-tal) — vagy elég egy gyors strukturált terv (válasz formájában, fájl nélkül)?" **User response paths**: - "yes" / "formal ADR" / "igen ADR" / "csináljuk" / "mehet az ADR" → proceed to Step 1 - "no" / "quick plan" / "gyors terv" / "csak egy terv" → DO NOT invoke this skill; respond conversationally with a structured plan (bullet points, alternatives if any, recommendation — but no `.md` artifact created) - Ambiguous → ask follow-up question, do NOT auto-invoke. Default = ASK rather than guess. ### Trivial — no ADR, no ask-back Obviously small request the LLM can confidently classify: - Method rename, variable rename - Single-file typo fix - Isolated bug fix (already-understood problem) - Doc tweak (formatting, link update, single-paragraph rewrite) - Code-comment improvement → Just do the work. No ADR ask-back. No invocation. ### Proactive flag (drift into architectural territory) When the conversation drifts into architecturally significant territory **WITHOUT** the user's explicit planning request — e.g., a "how does X work" thread that surfaces 2 alternative implementations the user is now mentally weighing — the LLM may proactively flag: > "Ez a beszélgetés architektúra-szintű választáshoz vezet ({observation — what specific signals you saw}). Érdemes lenne ADR-formába önteni — invokáljam az `adr-author` skill-t? (Jelezd, ha inkább folytassuk simán válaszként.)" Same complexity sniff as the implicit-planning case. **User confirmation always required** — never auto-invoke from a drift signal. ### When NOT to invoke - Trivial decisions: variable names, local refactors, formatting - "How does X work" questions → `docs-discovery` territory - Concrete implementation details (API signature specifics, SQL column types, exact loop structure) → these belong in code comments or the relevant topic doc - Already-decided topics covered by an existing ADR → dedupe: link to the existing ADR; optionally propose a supersession if the user wants to revisit - Simple bug fixes → `docs-check` surfaces these as `_ISSUES.md` entries ## Step 1 — Routing: which decision log? Two paradigms coexist in the workspace: | Paradigm | Location | Shape | Used for | |---|---|---|---| | **Per-repo ADR** (Nygard style) | `/docs/adr/NNNN-.md` | One file per decision | Product / code / domain architecture decisions | | **Decision log table** | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` | Table row with ID `LLMP-DEC-N` | Protocol-meta: rule changes, skill additions, instruction-file structural shifts | Heuristic: - Topic concerns `.github/`, `copilot-instructions.md`, skills, `[LOADED_DOCS]` format, Rule #1-5 → **LLMP table row** - Topic concerns code, domain, architecture, library choice, API shape, infrastructure → **per-repo ADR file** If ambiguous, ask the user explicitly before proceeding. **Path resolution for `docs/adr/`** — most ADRs are written for a new feature, refactor, or design decision in an established codebase where the convention is already settled. Don't overthink placement. **Common case (most ADRs)**: run `Glob /**/docs/adr/*.md`. If matches exist, use that established folder — convention is settled, no placement decision needed. **Never create a parallel `docs/adr/` elsewhere** in the same repo; fragmenting defeats sequential numbering, cross-references, and audit-ability. Placement IS a real decision only when no `docs/adr/` exists yet in the relevant scope. Two sub-cases: - **Fresh repo / first ADR ever**: default to `/docs/adr/` at the repo root. - **Multi-project repo, no `docs/adr/` anywhere yet**: match scope to placement — - **Cross-cutting decision** (affects 2+ projects, framework↔consumer boundary, or repo-wide concerns such as auth, logging conventions, build infrastructure) → place at the **highest common ancestor** of affected scopes, typically `/docs/adr/` at the repo root. - **Project-scoped decision** (one project's internal architecture only) → `//docs/adr/`. - **Ambiguous scope** → ask the user explicitly. Suggested phrasing: *"this decision touches projects X and Y — should the ADR live at the repo-root `docs/adr/` (cross-cutting) or scoped to one of those projects?"* **For any newly-created `docs/adr/` folder** (whether at repo root or project-scoped): propose creating `README.md` (2-3 lines explaining the ADR convention + an index table for new ADRs) and `0000-TEMPLATE.md` (a 1-paragraph pointer to the canonical `references/ADR_TEMPLATE.md` — single source of truth, avoids template drift). User confirms (Rule #5) before creation. The chosen location persists in git history and inbound cross-references (other ADRs, code comments, docs); relocating later requires updating every cross-ref. Getting placement right at creation is cheaper than fixing it. ## Step 2 — Establish context (Socratic) Ask, one at a time or in a short batch: 1. **Problem/opportunity** — what's the trigger? A symptom, constraint, or new requirement? 2. **Timing** — why decide NOW? (If "we don't actually need to decide yet" is the honest answer, exit cleanly and suggest a `_TODO.md` entry instead.) 3. **Scope boundaries** — what does this decision affect? What is explicitly OUT of scope? If the user answers "I don't know" to most of these, the decision isn't ripe. Gently suggest: explore the problem first, revisit when it's sharper. Exit skill. ## Step 3 — Surface alternatives Actively ask: "What options are you considering?" Then YOU add alternatives the user didn't mention — draw from loaded docs, known patterns, framework conventions. Aim for **minimum 2, ideally 3+** alternatives. If only 1 option is viable after honest thought, it's not a decision — it's an implementation path. Exit and suggest a `_TODO.md` entry. **Guardrail**: don't invent strawmen. Every alternative listed must be a genuinely considered option, not an obviously-bad filler to make the decision look rigorous. ## Step 4 — Trade-off elicitation For each alternative, capture: - **Pros** — what it enables / is good at - **Cons** — what it sacrifices / breaks - **Reversibility** — how expensive is it to undo later? - **Cost** — implementation time, complexity, operational burden - **Future flexibility** — does it close doors on future options? Keep it concise: 2-4 bullets per category per alternative. Not a dissertation. ## Step 5 — Decision capture **The user chooses. You never decide.** Your job is to surface, weigh, and ask clarifying questions. **When the user explicitly asks for your opinion** ("mi a véleményed?", "what do you think?", "which would you pick?"): share your weighing — but frame it as preference, not prescription. End with the user's decision still open. - ❌ Avoid: *"X is obviously the right choice."* / *"Path: repo-root, egyértelmű."* - ✅ Prefer: *"I lean toward X because Y, but you decide."* After the user commits: - Confident → `Status: Accepted (YYYY-MM-DD)` - Tentative/experimental → `Status: Proposed (YYYY-MM-DD)` — revisit later - Time-boxed → `Status: Accepted, review by YYYY-MM-DD` ## Step 6 — Consequences projection With loaded docs + the chosen decision, list consequences: - **Positive** — what this unlocks / improves - **Negative** — what it costs / breaks / constrains - **Follow-ups required** — "this decision requires updating X, Y, Z" Be concrete: reference specific files, types, or other docs when relevant. Vague consequences ("might affect performance") are less useful than specific ones ("adds ~200ms latency to the `/orders` endpoint under 10K+ items — see `PERFORMANCE.md`"). Follow-ups typically become either `_TODO.md` entries or new ADRs in their own right (if the follow-up is itself a significant sub-decision). ## Step 7 — Draft, review, write Assemble the draft using `references/ADR_TEMPLATE.md`. Show the draft to the user. The user reviews, requests changes; iterate as needed. **Only with explicit user approval** (Rule #5) write the file: ### Per-repo ADR write - Path: `/NNNN-.md` — `` is the location resolved in Step 1 (single-project repos default to `/docs/adr/`; multi-project repos follow the placement rules in Step 1's "Multi-project repo case"). - NNNN: zero-padded 4 digits (e.g., `0001`, `0042`). **Re-Glob `/*.md` immediately before the `Write` call** (not at draft time) — parallel sessions or interim work may have added entries; deriving NNNN at draft time risks collision. - ``: short kebab-case derived from the title (e.g., `cursor-based-pagination`, `postgres-over-mongo`). ### LLMP decision log write - File: `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` - Append one table row to the `## 2026` (or current year) section. - ID: derive the next `LLMP-DEC-N` from the max existing in the file + 1. - Condense the full ADR body into 4 columns: Decision (one line), Rationale (1-3 sentences), Affected (scope codes — see the file's own "Scope codes" section). ## Step 8 — Cross-references and follow-ups After the primary write: 1. **Quick-reference / index update** — append a new row to whichever ADR-index file exists in the repo. Most commonly: `/README.md` (which should have an Index table). Other patterns: `PRODUCT_DECISIONS.md` at the repo root, or none. If no index exists, propose creating one in `/README.md` as part of the same write. 2. **Supersession chain** — if this ADR supersedes an earlier one, edit the older ADR's `Status` line: `Superseded by ADR-NNNN (YYYY-MM-DD)`. 3. **Issue/TODO resolution** — two cases: - **Decision-closes-entry**: if this ADR's decision resolves an `Open` entry in `{TOPIC}_ISSUES.md` or `{TOPIC}_TODO.md`, propose updating those entries to `Status: Closed (YYYY-MM-DD)` with a `### Resolution` sub-section referencing this ADR (per `TOPIC_CODES.md` Status conventions). - **Pre-flight-closed-entry**: if an entry was closed BEFORE the ADR write (a pre-flight fix that this ADR formalizes architecturally), do NOT change its Status — it's already `Closed`. Instead, propose appending a soft cross-ref to the entry's `### Related` section: `**Reference:** ADR-NNNN — formal architectural decision; this entry's Resolution is the pre-flight fix referenced in the ADR's Consequences.` Do not apply either case without user consent. 4. **Follow-up TODOs** — if Step 6 surfaced follow-up work items, propose their addition to the relevant `_TODO.md` as new `--T-` entries (per `docs-check/references/TOPIC_CODES.md` ID format rules and `REPO_PREFIXES.md`'s prefix scheme). Do not apply without user consent. ## Step 9 — Hand-off after write After Steps 7 + 8 complete, do not assume what comes next. Ask the user explicitly: > "ADR-NNNN written and cross-references updated. What's next? Common options: commit changes / promote `Status: Proposed → Accepted (YYYY-MM-DD)` / start implementation work / open the next ADR for a related decision. Which?" Keep it short — let the user steer. If the user already indicated direction in earlier turns ("after this ADR, we'll start implementation"), reflect that in the hand-off rather than enumerating from scratch. ## Handoff with other skills - **`docs-check`** — when docs-check (at the end of a code-modifying response) notices an observation that looks ADR-worthy (irreversible decision landed in code; alternatives were actively weighed in the session; cross-cutting impact), it SHOULD flag: *"this may warrant an ADR — consider invoking `adr-author`"*. Does not auto-invoke. - **`docs-discovery`** — if the user's question is "how does X work" rather than "let's design X", `docs-discovery` owns the response, not this skill. - **`protocol-audit`** — unrelated; audits file-structural consistency, doesn't interact with ADR content. ## Tool usage Tool-neutral. Map to the host agent's tools: - Reading existing ADRs: `Read`, `Glob /docs/adr/*.md` - Writing new ADR: `Write` (new file) or `Edit` (append LLMP table row) - Dedupe check: `Grep` on existing ADR bodies for the topic keyword ## Edge cases - **Parallel LLM sessions / numbering collision**: covered by Step 7's "Re-Glob immediately before Write" rule. If two ADRs nonetheless end up with the same NNNN (concurrent writes within the glob-to-write window), the later writer re-numbers and updates cross-refs. Rare; manual resolution. - **User changes mind mid-interview**: if the user indicates "actually we don't need to decide this yet", exit cleanly. Offer to write a `_TODO.md` entry instead so the question isn't lost. - **Retroactive ADR for a decision already made in code**: legitimate. Document it honestly: `Status: Accepted (retroactive, YYYY-MM-DD), originally decided ~`. The value is the rationale preservation, even after-the-fact. - **Decision spans multiple repos**: write the primary ADR in the repo that owns the change most-centrally; add short `See /docs/adr/NNNN-.md` cross-refs in the other affected repos' ADR folders (under the same NNNN if possible; otherwise a free slot in each). - **User proposes an ADR for something trivial**: politely suggest `_TODO.md` instead. Don't lecture — just offer the lighter alternative once; if they still want an ADR, proceed.