AyCode.Core/.github/skills/adr-author/SKILL.md

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-<slug>.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)	<active-repo>/docs/adr/NNNN-<slug>.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 <repo>/**/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 <repo>/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 <repo>/docs/adr/ at the repo root.
  • Project-scoped decision (one project's internal architecture only) → <repo>/<project>/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: <adr-folder>/NNNN-<slug>.md — <adr-folder> is the location resolved in Step 1 (single-project repos default to <repo>/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 <adr-folder>/*.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.
• <slug>: 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: <adr-folder>/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 <adr-folder>/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 <TOPIC>_TODO.md as new <PREFIX>-<TOPIC>-T-<RAND> 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 <repo>/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 ~<when>. 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 <repo>/docs/adr/NNNN-<slug>.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.