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.
3.1 KiB
DECISIONS.md
This document defines how Architecture Decision Records (ADRs) work in Local LLC. The actual log of decisions lives in 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-adrin 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.