feat(skills): добавлен скилл brainstorm-with-docs (v1)
- Зачем:
- нужен ручной скилл для брейнсторма и дизайна, который удерживает
словарь смыслов (CONTEXT.md) и лёгкие ADR, активно прожаривает план
и не сваливается в реализацию.
- Что:
- SKILL.md: процесс (контекст → классификация → декомпозиция →
грилл → синтез опций → подтверждение → артефакт), единый HARD-GATE
«исследуй, но не меняй состояние» с поправкой на auto mode.
- artifacts/: шаблоны spec, research-note, adr, runbook, prd, context
(по файлу на тип для progressive disclosure).
- README.md с MIT-атрибуцией grill-with-docs (Pocock) и brainstorming
(obra/superpowers); шов для будущей фазы дивергенции в шаге 5.
- frontmatter переносим: Claude читает все поля, Codex — name+description.
- Проверка:
- python3 yaml-парс frontmatter; markdown-ссылки на artifacts/ резолвятся.
This commit is contained in:
ddadmin committed
1 parent
0a348da22a
commit
50640d8cb5
8 files changed
+572
No files matched your search
@@ -0,0 +1,81 @@
|
||||
# brainstorm-with-docs
|
||||
|
||||
A manually-invoked skill for **brainstorming, design alignment, and durable
|
||||
documentation** — grounded in a project's existing docs and vocabulary. It takes
|
||||
an unclear engineering, DevOps, architecture, migration, integration, research,
|
||||
or documentation problem and turns it into the *smallest useful* durable
|
||||
artifact: a spec, ADR, runbook, research note, or `CONTEXT.md` glossary update.
|
||||
|
||||
It is deliberately **not** an implementation skill. It reads project files and
|
||||
proposes documentation, but stops before code, config, or infrastructure changes
|
||||
— approval of a design direction is never approval to implement.
|
||||
|
||||
## Why this exists
|
||||
|
||||
It combines three things that are usually separate:
|
||||
|
||||
- **shared domain language** (glossary / `CONTEXT.md`) and **lightweight ADRs** —
|
||||
the discipline of capturing terminology and durable decisions as they crystallise;
|
||||
- **active grilling** — not just extracting requirements, but pressure-testing
|
||||
them: challenging terms against the glossary, sharpening fuzzy language, probing
|
||||
with edge-case scenarios, cross-checking claims against the code;
|
||||
- **option exploration** — always comparing 2-3 viable approaches with trade-offs
|
||||
before recommending a direction.
|
||||
|
||||
## Usage
|
||||
|
||||
Invoke manually:
|
||||
|
||||
```
|
||||
/brainstorm-with-docs <problem-or-topic>
|
||||
```
|
||||
|
||||
On **Claude Code** the skill is manual-only (`disable-model-invocation: true`) —
|
||||
it never auto-triggers; you always call it. On **Codex** that field is ignored
|
||||
(Codex reads only `name` + `description`), so it may auto-trigger on matching
|
||||
design tasks; the negative triggers in the description keep that disciplined.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
brainstorm-with-docs/
|
||||
├── SKILL.md # the skill: process, rules, grill mechanics
|
||||
├── README.md # this file
|
||||
└── artifacts/ # output templates — read only the one you need
|
||||
├── spec.md # solution design / engineering spec
|
||||
├── research-note.md # exploratory, answer not yet known
|
||||
├── adr.md # lightweight architectural decision record
|
||||
├── runbook.md # operational procedure
|
||||
├── prd.md # product-facing behaviour
|
||||
└── context.md # CONTEXT.md glossary format
|
||||
```
|
||||
|
||||
Templates are split per type so the agent loads only what's relevant
|
||||
(progressive disclosure).
|
||||
|
||||
## Roadmap
|
||||
|
||||
- **v1 (current):** working hybrid — context inspection, glossary/ADR discipline,
|
||||
active grilling, option comparison, durable artifacts, stop-before-implementation.
|
||||
- **v2 (planned):** a *divergence phase* before option synthesis (an
|
||||
idea-generation toolkit plus the rule "at least one option the user didn't
|
||||
already imply"), a "design for isolation" lens, and fuller multi-context
|
||||
support. A `<!-- SEAM -->` marker in `SKILL.md` step 5 marks where it slots in.
|
||||
|
||||
## Attribution
|
||||
|
||||
This is a derived, original skill — not a copy of either source. It borrows ideas
|
||||
from two MIT-licensed projects:
|
||||
|
||||
- **grill-with-docs / grill-me** by Matt Pocock —
|
||||
<https://github.com/mattpocock/skills> (MIT, © 2026 Matt Pocock).
|
||||
Source of the glossary/`CONTEXT.md` discipline, lightweight ADRs, and the
|
||||
active grilling techniques.
|
||||
- **brainstorming** by Jesse Vincent (obra), from Superpowers —
|
||||
<https://github.com/obra/superpowers> (MIT, © 2025 Jesse Vincent).
|
||||
Source of the explore-context → question → compare-options → present-design flow
|
||||
and the stop-before-implementation gate.
|
||||
|
||||
The `CONTEXT.md` and ADR formats are adapted from Matt Pocock's `grill-with-docs`
|
||||
companion files. Both upstream projects are MIT-licensed; see their repositories
|
||||
for full license text.
|
||||
@@ -0,0 +1,229 @@
|
||||
---
|
||||
name: brainstorm-with-docs
|
||||
description: Structured brainstorming and design alignment for unclear technical problems, grounded in the project's existing docs and vocabulary — questioning assumptions, sharpening terminology, comparing options, and recommending a direction. Use when exploring an ambiguous engineering, DevOps, architecture, migration, integration, research, or documentation problem and turning it into a durable artifact such as a spec, ADR, runbook, research note, or CONTEXT.md glossary update. Not for implementation, trivial fixes, or executing an already-approved plan.
|
||||
disable-model-invocation: true
|
||||
argument-hint: "[problem-or-topic]"
|
||||
allowed-tools: Read Grep Glob Write Edit WebSearch WebFetch Bash(git log:*) Bash(git diff:*) Bash(git status:*) Bash(git show:*)
|
||||
---
|
||||
|
||||
# Brainstorm With Docs
|
||||
|
||||
Move the user from an unclear problem to shared understanding, clear project
|
||||
language, viable options, a recommended direction, and the smallest useful
|
||||
durable documentation artifact. This skill is for thinking, alignment, and
|
||||
documentation — not for implementation.
|
||||
|
||||
<hard_gate>
|
||||
|
||||
Do NOT write code, change configuration or infrastructure, run state-changing
|
||||
commands, refactor, run migrations, deploy, or invoke any implementation skill
|
||||
until the user has approved a design AND explicitly asked to implement.
|
||||
|
||||
Approval of a design direction is NOT approval to implement. After producing or
|
||||
updating the agreed documentation artifact, STOP.
|
||||
|
||||
The skill may freely investigate — read project files, run read-only inspection
|
||||
commands, and look up external documentation — and may create or update
|
||||
documentation files once the user agrees on the direction. It must NOT change the
|
||||
state of any system: no code, config, or infrastructure changes; no data writes
|
||||
or migrations; no deployments; and no outward-facing actions other than read-only
|
||||
lookups.
|
||||
|
||||
If you are unsure whether a command has side effects — especially when querying a
|
||||
live or production system — state what you intend to run and why, and get a yes,
|
||||
before running it. Do not rely on the harness to stop you; in auto mode it may
|
||||
not.
|
||||
|
||||
</hard_gate>
|
||||
|
||||
<what_to_do>
|
||||
|
||||
Use this skill for:
|
||||
|
||||
* ambiguous engineering tasks
|
||||
* architecture or design decisions
|
||||
* DevOps and infrastructure work
|
||||
* research-heavy technical tasks
|
||||
* migration, integration, or operational-procedure design
|
||||
* choosing between implementation approaches
|
||||
* converting a discussion into a durable specification
|
||||
* clarifying project terminology and assumptions
|
||||
|
||||
Do not use this skill for:
|
||||
|
||||
* tiny mechanical edits or straightforward bug fixes with an obvious cause
|
||||
* simple code generation
|
||||
* pure execution of an already-approved plan
|
||||
* cases where the user explicitly asks to skip discussion and implement
|
||||
|
||||
If invoked with arguments, treat `$ARGUMENTS` as the initial problem statement.
|
||||
|
||||
</what_to_do>
|
||||
|
||||
<core_rules>
|
||||
|
||||
* Ask one question at a time when interviewing; wait for the answer.
|
||||
* Never ask for something the repository can answer — search first.
|
||||
* Prefer project-specific language over generic terminology.
|
||||
* Surface assumptions, constraints, risks, trade-offs, and non-goals.
|
||||
* Don't interview forever — when the problem, constraints, and success criteria
|
||||
are clear enough, stop asking and synthesize.
|
||||
* Always consider 2-3 viable approaches before recommending one.
|
||||
* Be direct. Give a real recommendation; don't hide behind "it depends" when the
|
||||
context supports a call.
|
||||
* Explicitly state what should NOT be done now.
|
||||
* Use the smallest artifact that preserves the useful thinking.
|
||||
* Keep `CONTEXT.md` strictly a glossary; create ADRs only sparingly.
|
||||
* Do not produce a detailed implementation plan unless the user asks for one.
|
||||
|
||||
</core_rules>
|
||||
|
||||
<how_to_do_it>
|
||||
|
||||
## 1. Inspect project context
|
||||
|
||||
Before asking the user anything, read the relevant context. Prefer this order:
|
||||
|
||||
1. `AGENTS.md` or an equivalent project map
|
||||
2. README / project overview
|
||||
3. `docs/`, then existing specs and design docs
|
||||
4. ADRs (`docs/adr/`), runbooks, status docs
|
||||
5. code and config relevant to the problem
|
||||
|
||||
Look for: existing terminology, decisions already made, known constraints,
|
||||
previously rejected options, deployment model, testing/validation conventions,
|
||||
and patterns the solution should follow. Respect a documented structure if one
|
||||
exists. If no context is available, say so and continue with what the user gives.
|
||||
|
||||
## 2. Classify the work and pick the likely artifact
|
||||
|
||||
Decide what kind of work this is, then which artifact is likely to fit:
|
||||
|
||||
* answer still unknown → [research note](artifacts/research-note.md)
|
||||
* direction chosen, not yet built → [spec / solution design](artifacts/spec.md)
|
||||
* durable, surprising, hard-to-reverse trade-off → [ADR](artifacts/adr.md)
|
||||
* operational procedure / recovery / diagnostics → [runbook](artifacts/runbook.md)
|
||||
* shared project vocabulary → [`CONTEXT.md` glossary](artifacts/context.md)
|
||||
* product-facing, user-visible behaviour → [PRD](artifacts/prd.md)
|
||||
|
||||
Don't force everything into a PRD. Read an artifact's file only when you're
|
||||
actually about to write that kind of artifact.
|
||||
|
||||
## 3. Check scope and decompose if needed
|
||||
|
||||
Before deep brainstorming, check whether this is one coherent problem or several.
|
||||
If it's too broad, pause and propose a decomposition — separating research from
|
||||
implementation, design from execution, product requirements from engineering
|
||||
design, one-time setup from recurring operations, reversible from hard-to-reverse
|
||||
decisions. Ask which part to handle first.
|
||||
|
||||
## 4. Interview / grill
|
||||
|
||||
Interview the user until the problem is clear enough to synthesize. One question
|
||||
at a time. When the reason for a question isn't obvious, briefly say why it
|
||||
matters. Prefer questions that clarify: the actual problem and why it matters,
|
||||
expected outcome, who is affected, constraints, non-goals, success criteria,
|
||||
failure modes, operational and security risks, reversibility, deadlines or
|
||||
sequencing, what's been tried, and what must not change.
|
||||
|
||||
Grill actively — don't just collect answers, pressure-test them:
|
||||
|
||||
* **Challenge against the glossary.** If a term conflicts with `CONTEXT.md`, call
|
||||
it out: "Your glossary defines 'cancellation' as X, but you mean Y — which?"
|
||||
* **Sharpen fuzzy language.** Propose a precise canonical term for vague or
|
||||
overloaded words: "You say 'account' — Customer or User? Those differ."
|
||||
* **Probe with concrete scenarios.** Invent edge cases that force precision about
|
||||
the boundaries between concepts.
|
||||
* **Cross-reference with code.** When the user states how something works, check
|
||||
the code agrees; surface contradictions: "Your code cancels whole Orders, but
|
||||
you said partial cancellation is possible — which is right?"
|
||||
|
||||
Capture resolved terms in `CONTEXT.md` inline, as they happen, using the format
|
||||
in [artifacts/context.md](artifacts/context.md) — don't batch them.
|
||||
|
||||
## 5. Synthesize options
|
||||
|
||||
<!-- SEAM: v2 will prepend a divergence phase (idea-generation toolkit +
|
||||
"at least one option the user didn't already imply") before this
|
||||
convergence step. Keep this step self-contained so it can be split. -->
|
||||
|
||||
Present 2-3 viable approaches. For each: short description, when it fits,
|
||||
benefits, trade-offs, risks, operational implications, documentation impact, and
|
||||
what it avoids or postpones. Then recommend one, explaining why it fits the
|
||||
constraints, what risks remain, what to validate first, and what to explicitly
|
||||
not do now.
|
||||
|
||||
## 6. Confirm direction
|
||||
|
||||
Before writing or changing durable project documents, confirm the direction.
|
||||
Confirmation can be lightweight, e.g.:
|
||||
|
||||
> "I recommend option B. I'd document it as a solution design, add one
|
||||
> lightweight ADR for the storage-layout decision, and add two terms to
|
||||
> `CONTEXT.md`. Does that match your intent?"
|
||||
|
||||
Don't ask permission for every wording choice, but DO confirm before: creating a
|
||||
spec, creating an ADR, changing architectural direction, or changing documented
|
||||
vocabulary.
|
||||
|
||||
## 7. Write the artifact
|
||||
|
||||
Once the user agrees, create or update the artifact, following the format in the
|
||||
matching `artifacts/*.md` file. Choose the smallest form that preserves the
|
||||
thinking.
|
||||
|
||||
Where it goes: follow the repo's existing documentation layout if there is one.
|
||||
Otherwise use the conventional homes — `CONTEXT.md` at the repo root, ADRs in
|
||||
`docs/adr/`, and other artifacts under `docs/` (e.g. `docs/specs/`,
|
||||
`docs/runbooks/`). If the location isn't obvious, propose a path and confirm it
|
||||
as part of step 6 rather than guessing. Create directories lazily.
|
||||
|
||||
Then go to `<validation>` and `<stop_condition>`.
|
||||
|
||||
</how_to_do_it>
|
||||
|
||||
<shared_project_language>
|
||||
|
||||
`CONTEXT.md` is only for shared project language: domain terms, project-specific
|
||||
concepts, preferred names, terms to avoid, and short relationships between
|
||||
concepts when they clarify language. It is a glossary, not a spec, work log, ADR
|
||||
store, validation plan, or list of rejected alternatives.
|
||||
|
||||
While interviewing, watch for terms that are ambiguous, overloaded, used
|
||||
inconsistently, or missing from shared docs. If a durable term matters to future
|
||||
work, propose adding it. Full format and rules: [artifacts/context.md](artifacts/context.md).
|
||||
|
||||
If something is a decision → spec or ADR. If it's an operational procedure →
|
||||
runbook. If it's a validation rule for this work → the spec.
|
||||
|
||||
</shared_project_language>
|
||||
|
||||
<validation>
|
||||
|
||||
Before presenting the final artifact, review it for: unclear terms, missing
|
||||
constraints, hidden assumptions, contradictions with existing docs, unnecessary
|
||||
scope expansion, premature implementation detail, missing validation criteria,
|
||||
decisions that should (or should not) be ADRs, operational steps that should be a
|
||||
runbook, and context that does (or does not) belong in `CONTEXT.md`.
|
||||
|
||||
If it's too large, propose splitting it. If it's too vague, continue the
|
||||
interview.
|
||||
|
||||
</validation>
|
||||
|
||||
<stop_condition>
|
||||
|
||||
After the artifact is produced, STOP. Do not start coding, change
|
||||
infrastructure, alter configuration, or run state-changing commands unless the
|
||||
user explicitly asks. Offer a small set of next actions, such as:
|
||||
|
||||
* refine the spec
|
||||
* create or update an ADR
|
||||
* update `CONTEXT.md`
|
||||
* create a runbook
|
||||
* derive a compact implementation checklist
|
||||
* start implementation (only on explicit request)
|
||||
|
||||
Do not proceed automatically.
|
||||
|
||||
</stop_condition>
|
||||
@@ -0,0 +1,40 @@
|
||||
# ADR — Architectural Decision Record
|
||||
|
||||
ADRs live in `docs/adr/` with sequential numbering: `0001-slug.md`,
|
||||
`0002-slug.md`, etc. Create `docs/adr/` lazily — only when the first ADR is
|
||||
needed. To number a new one, scan `docs/adr/` for the highest number and add one.
|
||||
|
||||
## When to offer an ADR
|
||||
|
||||
Offer one only when **all three** are true:
|
||||
|
||||
1. **Hard to reverse** — the cost of changing your mind later is meaningful.
|
||||
2. **Surprising without context** — a future reader will look at the code and
|
||||
wonder "why on earth did they do it this way?"
|
||||
3. **The result of a real trade-off** — there were genuine alternatives and one
|
||||
was picked for specific reasons.
|
||||
|
||||
If any of the three is missing, skip it. Easy to reverse → you'll just reverse
|
||||
it. Not surprising → nobody will wonder. No real alternative → nothing to record
|
||||
beyond "we did the obvious thing". Do not create an ADR for every small choice.
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# {Short title of the decision}
|
||||
|
||||
{1-3 sentences: what's the context, what we decided, and why.}
|
||||
```
|
||||
|
||||
That's it. An ADR can be a single paragraph. The value is recording *that* a
|
||||
decision was made and *why* — not in filling out sections.
|
||||
|
||||
## Optional sections
|
||||
|
||||
Add these only when they earn their place (most ADRs won't need them):
|
||||
|
||||
- **Status** frontmatter (`proposed | accepted | deprecated | superseded by
|
||||
ADR-NNNN`) — useful when decisions get revisited.
|
||||
- **Considered options** — only when the rejected alternatives are worth
|
||||
remembering (otherwise someone re-proposes them in six months).
|
||||
- **Consequences** — only when non-obvious downstream effects need calling out.
|
||||
@@ -0,0 +1,53 @@
|
||||
# CONTEXT.md — Shared Project Language
|
||||
|
||||
`CONTEXT.md` is a **glossary and nothing else**. It exists so that the user, the
|
||||
code, and future agents use the same words for the same concepts. It is totally
|
||||
devoid of implementation details, decisions, plans, or work logs.
|
||||
|
||||
A single `CONTEXT.md` lives at the repo root. If a `CONTEXT-MAP.md` exists at the
|
||||
root, the repo has multiple contexts — read it to find which `CONTEXT.md` the
|
||||
current topic belongs to. (Multi-context handling is deliberately light in v1.)
|
||||
|
||||
Create the file lazily — only when the first term is actually worth recording.
|
||||
|
||||
## Structure
|
||||
|
||||
```markdown
|
||||
# {Context Name}
|
||||
|
||||
{One or two sentences: what this context is and why it exists.}
|
||||
|
||||
## Language
|
||||
|
||||
**Order**:
|
||||
A customer's request to purchase one or more items.
|
||||
_Avoid_: Purchase, transaction
|
||||
|
||||
**Invoice**:
|
||||
A request for payment sent to a customer after delivery.
|
||||
_Avoid_: Bill, payment request
|
||||
|
||||
**Customer**:
|
||||
A person or organisation that places orders.
|
||||
_Avoid_: Client, buyer, account
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **Be opinionated.** When several words mean the same thing, pick the best one
|
||||
and list the rest under `_Avoid_`.
|
||||
- **Keep definitions tight.** One or two sentences. Define what it *is*, not what
|
||||
it *does*.
|
||||
- **Only project-specific terms.** General programming concepts (timeouts, retry,
|
||||
cache) don't belong, even if the project uses them heavily. Ask: is this unique
|
||||
to this project's domain, or generic? Only the former belongs.
|
||||
- **Group under subheadings** when natural clusters emerge; a flat list is fine
|
||||
otherwise.
|
||||
|
||||
## What does NOT go in CONTEXT.md
|
||||
|
||||
- implementation details
|
||||
- specs, decisions, or rejected alternatives → spec / ADR
|
||||
- operational procedures → runbook
|
||||
- validation rules for the current work → spec
|
||||
- work logs, temporary notes, speculative ideas
|
||||
@@ -0,0 +1,38 @@
|
||||
# PRD — Product Requirements Document
|
||||
|
||||
Use **only** for product-facing work with user-visible behaviour. For internal
|
||||
engineering, infra, or architecture work use `artifacts/spec.md` instead — don't
|
||||
force everything into a PRD.
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Title
|
||||
|
||||
## Problem statement
|
||||
|
||||
## Users
|
||||
|
||||
## Goals
|
||||
|
||||
## Non-goals
|
||||
|
||||
## User stories
|
||||
|
||||
## Requirements
|
||||
|
||||
## Out of scope
|
||||
|
||||
## Success criteria
|
||||
|
||||
## Open questions
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- A PRD describes *what* and *why* from the user's point of view, not *how*. The
|
||||
engineering "how" belongs in a spec.
|
||||
- **Non-goals** and **Out of scope** are deliberately separate: non-goals are
|
||||
things we chose not to optimise for; out of scope is work explicitly deferred.
|
||||
- **Success criteria** must be observable — how will we know the behaviour is
|
||||
right once shipped?
|
||||
@@ -0,0 +1,38 @@
|
||||
# Research Note
|
||||
|
||||
Use when the work is exploratory and the final answer is not yet known. The
|
||||
output is *findings and a direction*, not a committed design.
|
||||
|
||||
When the question is resolved, the research note often graduates into a spec
|
||||
(`artifacts/spec.md`) or an ADR (`artifacts/adr.md`).
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Title
|
||||
|
||||
## Question
|
||||
|
||||
## Context
|
||||
|
||||
## Known facts
|
||||
|
||||
## Assumptions
|
||||
|
||||
## Options / hypotheses
|
||||
|
||||
## Findings
|
||||
|
||||
## Recommendation
|
||||
|
||||
## Remaining unknowns
|
||||
|
||||
## Next checks
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep **Known facts** and **Assumptions** strictly separate. Conflating them is
|
||||
how a guess hardens into an unexamined "fact".
|
||||
- **Remaining unknowns** and **Next checks** are what make a research note
|
||||
useful to the next agent — they say where to dig next.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Runbook
|
||||
|
||||
Use for operational procedures: diagnostics, verification, recovery, deployment,
|
||||
or routine maintenance. A runbook is for *doing*, so optimise for someone
|
||||
following it under pressure — concrete commands, expected output, clear failure
|
||||
branches.
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Title
|
||||
|
||||
## Purpose
|
||||
|
||||
## When to use
|
||||
|
||||
## Preconditions
|
||||
|
||||
## Procedure
|
||||
|
||||
## Verification
|
||||
|
||||
## Rollback / recovery
|
||||
|
||||
## Known failure modes
|
||||
|
||||
## Notes
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- **Procedure** steps should be copy-pasteable where possible, with the expected
|
||||
result after each consequential step.
|
||||
- **Verification** is how the operator confirms success — not "it should work"
|
||||
but "run X, expect Y".
|
||||
- **Rollback / recovery** and **Known failure modes** are what separate a
|
||||
runbook from a tutorial. If you can't say how to undo it, say that explicitly.
|
||||
@@ -0,0 +1,56 @@
|
||||
# Solution Design / Spec
|
||||
|
||||
Use for engineering, architecture, DevOps, integration, migration, or any
|
||||
non-product feature work where a direction has been chosen but not yet built.
|
||||
|
||||
Use the smallest version that preserves the useful thinking. Drop sections that
|
||||
add nothing for this particular problem — an empty section is noise.
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Title
|
||||
|
||||
## Problem
|
||||
|
||||
## Context
|
||||
|
||||
## Goals
|
||||
|
||||
## Non-goals
|
||||
|
||||
## Current state
|
||||
|
||||
## Options considered
|
||||
|
||||
## Recommended approach
|
||||
|
||||
## Rationale
|
||||
|
||||
## Decisions and rejected alternatives
|
||||
|
||||
## Risks and mitigations
|
||||
|
||||
## Validation
|
||||
|
||||
## Documentation impact
|
||||
|
||||
## Open questions
|
||||
```
|
||||
|
||||
## Notes on key sections
|
||||
|
||||
**Decisions and rejected alternatives** is the highest-value section. Capture:
|
||||
|
||||
- accepted decisions and the reason behind each
|
||||
- rejected alternatives and *why* they were rejected
|
||||
- subtle constraints and important defaults
|
||||
- sequencing decisions
|
||||
- assumptions future agents must not silently re-derive
|
||||
|
||||
Do not turn this section into an ADR dump. Promote a decision to its own ADR
|
||||
(`artifacts/adr.md`) only when it is durable, surprising, and the result of a
|
||||
real trade-off.
|
||||
|
||||
**Validation** describes how we will know the implementation is correct — tests,
|
||||
checks, acceptance criteria. It belongs here, not in `CONTEXT.md`.
|
||||
Reference in new issue
Block a user