Christopher Clendening
96b7ff9766
- Create SECURITY.md to outline security policies and practices. - Establish WORKFLOW.md detailing the project lifecycle from planning to retrospective. - Introduce decision log structure in decisions/README.md for tracking architecture decisions. - Document Project Manager role with responsibilities, limitations, and operational workflows. - Implement templates for ADRs, bugs, meetings, projects, retrospectives, RFCs, roadmaps, and sprints. - Set up memory logs for architecture and company-wide lessons learned. - Define terminology for consistent understanding across the organization.
70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
# DECISIONS.md
|
|
|
|
This document defines how Architecture Decision Records (ADRs) work in Local LLC. The actual
|
|
log of decisions lives in [decisions/](decisions/) — this file is policy, that directory is the
|
|
record.
|
|
|
|
## What is an ADR
|
|
|
|
A short document capturing a decision with lasting technical consequence: something that would
|
|
be expensive or disruptive to reverse, or that future engineers need to understand the reasoning
|
|
behind rather than just the outcome. An ADR is not a design doc, a PR description, or meeting
|
|
notes — it's a permanent record of "we decided X, here's why, here's what we considered instead."
|
|
|
|
## When to write one
|
|
|
|
Write an ADR before implementing, not after, when a decision:
|
|
|
|
- Changes how multiple projects or roles interact with shared infrastructure (Gitea, ACT
|
|
Runner, Plane conventions).
|
|
- Introduces a new architectural pattern, major dependency, or technology choice a project will
|
|
build on.
|
|
- Reverses or significantly amends a previous ADR.
|
|
- Is flagged `needs-adr` in Plane by the Architect (`PLANE.md`).
|
|
|
|
Don't write one for routine implementation choices already covered by `CODING_STANDARDS.md` — an
|
|
ADR is for decisions that standard doesn't already settle.
|
|
|
|
## Who writes and approves them
|
|
|
|
- Any engineering role can draft an ADR when they hit a decision point that qualifies.
|
|
- The Architect approves it before it's considered accepted — this is the Architect's core
|
|
authority per `ORGANIZATION.md`.
|
|
- Decisions with company-wide, irreversible impact (per `FOUNDER.md`'s approval table) still
|
|
require Founder sign-off in addition to Architect approval — the Architect approving a
|
|
technically sound ADR does not itself clear the Founder's approval gate for decisions that
|
|
belong there.
|
|
|
|
## Process
|
|
|
|
```
|
|
1. Draft using templates/ADR.md
|
|
2. Open as a PR against decisions/ (numbered, see below)
|
|
3. Architect reviews — approves, requests changes, or rejects with reasoning
|
|
4. If it qualifies as Founder-gate territory (FOUNDER.md), get that sign-off too
|
|
5. Merge — status becomes "Accepted"
|
|
6. If later reversed, a NEW ADR supersedes it — the old one's status changes to
|
|
"Superseded by ADR-00XX", it is never deleted or rewritten
|
|
```
|
|
|
|
## Numbering and location
|
|
|
|
Files live in `decisions/` as `NNNN-short-title.md`, numbered sequentially starting at `0001`.
|
|
Numbers are never reused, even for a rejected or later-superseded ADR — the log is append-only.
|
|
`decisions/README.md` is the index.
|
|
|
|
## Format
|
|
|
|
Use `templates/ADR.md`. At minimum: Status, Context, Decision, Consequences, Alternatives
|
|
Considered. An ADR that only states the decision without the alternatives considered isn't
|
|
useful to the next engineer who wonders "why not X instead" — include enough of the "why not"
|
|
to make that question unnecessary to re-ask.
|
|
|
|
## Relationship to project docs
|
|
|
|
A project's `PROJECT.md` (`templates/PROJECT.md`) should link the ADRs that shaped it. An ADR
|
|
is company-wide by default (in `decisions/`), even when it was motivated by one project — if a
|
|
decision is genuinely project-specific and has no bearing beyond that project, it can live in
|
|
the project's own folder instead, but default to the shared log unless there's a clear reason
|
|
not to.
|