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 version: "1.0"

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 user triggers

• "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 <tech-stack/library/pattern>", "choose an approach to V"
• "milyen megközelítést", "what's our approach to W"
• "create an ADR for …", "write a decision record about …"

LLM-suggest-back (you flag, user confirms)

When the current conversation exhibits two or more of these heuristics, flag the user:

• Multiple alternatives being actively weighed
• Decision that is irreversible or expensive to reverse
• Cross-cutting impact (touches 2+ modules, or framework↔consumer boundary)
• A question someone might reasonably re-open in 6-18 months and ask "wait, why did we pick this?"
• Non-trivial dependency or library choice
• New public-facing API shape being discussed

Example flag phrasing:

"Ez egy architektúra-szintű választásnak tűnik (több alternatíva, irreverzibilis lehet). Érdemes lenne ADR-formába önteni — invokáljam az adr-author skill-t? (Jelezd, ha inkább folytassuk simán válaszként.)"

User confirmation is required before proceeding to Step 1. Never auto-invoke.

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. Propose creating it with README.md (2-3 lines explaining the convention) and 0000-TEMPLATE.md (copy of references/ADR_TEMPLATE.md). User confirms (Rule #5) before creation.

• 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?"

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. 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). Derive from Glob <adr-folder>/*.md and take max+1.
• <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 update — if the repo has a PRODUCT_DECISIONS.md (or equivalent ADR index), append a new row.
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 — if this decision closes an open entry in {TOPIC}_ISSUES.md or {TOPIC}_TODO.md, propose updating those entries with Status: RESOLVED by ADR-NNNN. Do not apply 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 {TOPIC}-T-N entries. Do not apply without user consent.

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: derive NNNN at the moment of write, not earlier. If two ADRs end up with the same number, 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.