keisei/KeiSeiKit-1.0
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
KeiSeiKit-1.0/_blocks/docs-decisions-adr.md
Parfii-bot 0be354a920 KeiSeiKit-public — clean state 
Single-commit clean baseline after security scrub of niche-tells,
project codenames, internal jargon, and contributor-email leaks.

Contents:
- 100 Rust crates (_primitives/_rust/)
- 37 agent manifests (_manifests/) + generated specs (_generated/)
- 67 user-invocable skills (skills/)
- 33 hooks (hooks/)
- Composition blocks (_blocks/)
- Documentation (docs/, README.md)
- TS adapter packages (_ts_packages/)
- Assembler (_assembler/)
- Roles (_roles/)
- Templates (_templates/)
- Forgejo CI (.forgejo/)

Author: Denis Parfionovich <info@greendragon.info>

License: see LICENSE.
2026-05-01 12:09:03 +08:00

2.1 KiB
Raw Blame History

DOCS — DECISIONS.md / ADR template (MADR 4.0)

Architecture Decision Records capture why a non-trivial choice was made, so future maintainers (including agents) don't re-litigate. Format: MADR 4.0 (Markdown Any Decision Records, 2024). Nygard originated the practice in 2011.

One ADR per non-trivial decision. File path convention:

  • Single-file log: append to DECISIONS.md (top-of-file = newest).
  • Per-decision files: docs/adr/NNNN-kebab-case-title.md (NNNN = zero-padded int).

MADR 4.0 template (copy as-is):

# ADR-NNNN: <short imperative title>

- **Status:** Proposed | Accepted | Rejected | Superseded-by-ADR-NNNN | Deprecated
- **Date:** YYYY-MM-DD
- **Deciders:** @handle, @handle
- **Evidence grade:** E1-E6 (see `_blocks/evidence-grading.md`)

## Context and Problem Statement
<1-3 sentences: what forces us to decide? What breaks if we don't?>

## Decision Drivers
- Driver 1 (e.g. cost < $X/mo)
- Driver 2 (e.g. must run offline)
- Driver 3 (e.g. team knows language Y)

## Considered Options
1. **Option A** — one-line summary
2. **Option B** — one-line summary
3. **Option C** — one-line summary

## Decision Outcome
Chosen: **Option <letter>**, because <1-2 sentences tying back to drivers>.

### Consequences
- Positive: <what improves>
- Negative: <what we give up, tech debt incurred>
- Neutral: <noteworthy but not directional>

## Pros and Cons of the Options
### Option A
- Pro: ...
- Con: ...
### Option B
- Pro: ...
- Con: ...

## Links
- Supersedes: ADR-NNNN
- Related: `HOTPATHS.md#section`, external URL
- Evidence source: [VERIFIED: url] or [UNVERIFIED]

Rules:

  • Status Accepted = implemented or actively being implemented. Proposed = under review. Rejected stays as an ADR (the record of why we said no).
  • Never delete a past ADR. Supersede with a new ADR that references the old number.
  • Evidence grade mandatory (RULE 0.4). No grade → the ADR is unreviewable.

Source: MADR 4.0 spec — adr/madr [E4]. Nygard 2011 original post cognitect.com/blog/2011/11/15/documenting-architecture-decisions [E4].