Adr Discovery

adr-discovery

Pre-flight context gathering for an ADR. The output is a docs/architecture/discovery-brief.md containing only human-confirmed facts, plus a docs/architecture/open-questions.md register of unknowns. The architect then hands off to adr-drafting to actually draft the decision.

Core rule: zero hallucination

No fact enters the discovery brief until the architect says yes. Code findings, doc findings, and inferences are all presented as questions, never as assertions.

Every confirmed fact is dated and tagged in the brief: [CONFIRMED YYYY-MM-DD]. Unconfirmed code findings get [FROM CODE, UNCONFIRMED YYYY-MM-DD] and live in open-questions.md, not the brief.

Fact states

Vocabulary (define on first use)

• Component — a runnable / deployable unit (C4 Container). Not a code class.
• System — the one bounded product in focus for this ADR. Exactly one.
• External system — a system the team does not own but interacts with.
• Actor — a human role (Person in C4 terms).
• Architectural characteristic — the non-functional quality under pressure (latency, cost, maintainability, availability, security posture, etc.).
• Tension — two ADRs that conflict without one superseding the other. A tension is a fact, not a failure; it must be acknowledged.
• RFC — a proposal-stage doc. ADRs are for decisions already made.

Style

• One topic at a time. Never ask two questions in one turn.
• Restate the architect's answer in your own words before recording it.
• Direct. Skip "Great question!", "Excellent!", and other affirmations.
• Name specific files, tech, and components — never vague nouns ("the service," "the database").
• If a turn would contain more than one ? or run more than a short paragraph, shorten it.

The nine phases

1. Scan, don't summarize

Glob the repo for signals — never assert what you find.

• ADR directories: docs/adr/, docs/decisions/, docs/architecture/decisions/, **/adr/*.md; also check legacy architecture/decisions/ and warn it may need custom ADR Explorer root configuration
• Manifests: package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, *.csproj
• READMEs at the repo root and one level down
• LikeC4 files: **/*.c4, likec4.config.*
• Existing discovery-brief.md / open-questions.md

Report raw findings only: "I found these files: X, Y, Z. I have not interpreted them yet." Then ask: "Should I walk through them with you one at a time, or do you want to start from a clean slate?"

Optionally offer live diagram mode — see references/live-diagram-mode.md — but only after the architect opts in.

2. Confirm domain

Ask exactly one question: "What does this system do, and for whom?"

Wait for an answer. Restate. Confirm. Then write a single Domain: line to the brief.

3. Confirm components one at a time

Define Component (a C4 Container — a deployable unit). Then walk candidates one by one. For each:

1. State the candidate name as you found it (in the manifest, the README, the LikeC4 file, or the architect's words). 2. Ask: "Is this a component in scope for this decision? (yes / no / out of scope)" 3. If yes: ask for a one-line description in the architect's words. 4. If no: drop it. 5. Hard limit: 5 components. If the architect names a 6th, ask whether the decision is bundled.

4. Confirm relationships with human-written descriptions

For each confirmed component pair, ask: "Does A depend on B? If yes, in one line, what does A use B for?"

A relationship without a human-written description does not enter the brief. "A talks to B" is not a description.

5. Confirm existing ADRs

Glob the ADR directory. For each ADR, ask one of:

• Supersedes? — does this new decision replace this prior one?
• Amends? — does it adjust without replacing?
• Relates-to? — does it share context but stand alone?
• Tension? — does it conflict, with neither superseding?
• Unrelated? — drop it.

Only the architect's answer enters the brief. Inference does not.

6. Multi-repo + ecosystem probe

Many decisions cross repo boundaries. Ask per related repo:

• Role (consumer / producer / shared library / platform)
• Owner (named team or person)
• Access (read / write / no access)
• Existing ADRs in that repo
• Existing C4 / architecture diagrams

Beyond repos, ask whether the org has:

• A wiki / Backstage / TechRadar / platform-level ADR set
• Compliance constraints (data residency, SOC2, HIPAA, GDPR, FedRAMP) that bind the decision
• A platform team whose decisions the architect inherits

7. Checklist gate

Before hand-off, all five MUSTs must be CONFIRMED:

If any MUST is UNKNOWN or PARKED, the skill refuses to advance and routes to open-questions.md.

8. C4 handoff (optional)

If the architect wants a diagram before drafting, hand off to c4-model (canonical C4: Context + Container views only). Skip if they don't.

9. Handoff to drafting

When all five MUSTs are confirmed, write a one-line summary at the bottom of discovery-brief.md:

Discovery complete: 2026-05-20. Hand off to adr-drafting.

The drafting skill reads the brief and does not re-ask anything in it.

Living files (kept deliberately outside ADR-parsed directories)

docs/architecture/discovery-brief.md and docs/architecture/open-questions.md are intentionally not under docs/adr/, so ADR-parser tools and indexes don't mistake them for ADRs.

discovery-brief.md shape

# Discovery Brief

## Domain
[CONFIRMED 2026-05-20] One sentence -- what does the system do, for whom.

## System in focus
[CONFIRMED 2026-05-20] Single named system.

## Architectural characteristic under pressure
[CONFIRMED 2026-05-20] e.g., "p95 read latency < 200ms on cross-entity reports."

## Components in scope (≤5)
[CONFIRMED 2026-05-20] - Name -- one-line description (architect's words)
...

## Relationships
[CONFIRMED 2026-05-20] - A → B: A uses B to <verb phrase>
...

## External actors
[CONFIRMED 2026-05-20] - Role -- one-line description
...

## Existing ADRs in play
[CONFIRMED 2026-05-20] - 0007 -- supersedes / amends / relates-to / tension

## Repos in play
[CONFIRMED 2026-05-20] - repo: role / owner / access / ADRs / C4

## Ecosystem constraints
[CONFIRMED 2026-05-20] - Compliance, platform, wiki/Backstage hits

## Decision-makers
[CONFIRMED 2026-05-20] - Named human(s)

---
Discovery complete: 2026-05-20. Hand off to adr-drafting.

open-questions.md shape — see references/open-questions-register.md for the full schema.

The "ADR IS NOT" rules apply here too

Even during discovery, do not tutorialize, hedge, or invent. See ../_shared/adr-is-not.md for the shared checklist.

References

• references/live-diagram-mode.md — opt-in LikeC4 live-diagram workflow during discovery
• references/open-questions-register.md — schema and discipline for open-questions.md
• ../_shared/adr-is-not.md — shared "ADR is not" checklist

Live-diagram mode (opt-in, during discovery)

A workflow for architects who think visually. The discovery skill can render a LikeC4 diagram incrementally as facts are confirmed, so the architect sees the system shape emerging. This is opt-in — never start it without asking.

Pre-flight checks

Before offering, verify:

1. LikeC4 CLI installed — npx likec4 --version returns a version (any v1.47+). 2. Port 5173 free — likec4 start defaults to this port; offer an alternative if busy. 3. No existing `likec4/` directory at the repo root — if there is one, ask whether to extend it or scaffold a fresh likec4-discovery/ sandbox so discovery doesn't pollute the canonical model.

Scaffold

Create three files under likec4-discovery/ (or the chosen path):

• model.c4 — the spec block + an empty model
• views.c4 — one context view and one container view of the system in focus
• likec4.config.js — minimal config pointing at the two .c4 files

Use the canonical-C4 specification block from the c4-model skill. Do not invent custom element kinds or styles during discovery.

Incremental write

As each component, relationship, or actor is confirmed in discovery:

1. Append a line to model.c4. 2. Save. 3. The LikeC4 server hot-reloads; the architect sees the diagram update.

Open-question tagging

When a confirmed-but-incomplete element appears (e.g., "this component exists, but the architect hasn't named its tech yet"):

• Tag the element #open-question
• Prefix its description with OPEN Q<N>: matching the entry number in open-questions.md
• The canonical style renders #open-question as red + dashed, so unknowns are visually obvious

What live mode does NOT do during discovery

• Does not run likec4 validate — that belongs in the c4-model skill.
• Does not add scoped views, styled views, deployment views, or component views.
• Does not apply custom styling.
• Does not commit to a final model — the architect copies confirmed elements into the canonical likec4/ directory only after discovery completes, via c4-model.

The diagram during discovery is a thinking aid, not a deliverable.

Tearing down

When discovery completes:

• Offer to delete likec4-discovery/ (the sandbox)
• Offer to graduate the confirmed elements into likec4/ via c4-model
• Stop the likec4 start server gracefully

Never auto-promote the sandbox model to the canonical one — let c4-model do that with its own lint pass.

open-questions.md — schema and discipline

The open-questions register lives at docs/architecture/open-questions.md, deliberately outside any directory an ADR parser walks. It is the single home for unknowns that surface during discovery, drafting, or critique.

Why a separate file

• Unknowns are not decisions; they should not pollute the ADR log.
• Unknowns have lifecycles (open → answered / parked) and owners — they deserve a register, not a scattered set of TODO comments.
• ADR-parser tooling typically globs docs/adr/** or docs/architecture/decisions/**; placing the register one level up keeps tooling honest.

Entry shape

Each entry is a short numbered block:

## Q12 -- Should we run Postgres single-region or multi-region?

- **Status:** OPEN
- **Why it matters:** ASR-7 requires read latency < 50ms p95 for EU users; single-region from us-east-1 is ~110ms.
- **Where to look:** existing RDS dashboard (cloudwatch/rds-latency), product roadmap on EU expansion, finance for cross-region transfer cost.
- **Who to ask:** Priya (Platform), Marcus (Finance), product owner for EU launch.
- **Raised:** 2026-05-20 during discovery for ADR-0016 (Postgres adoption).
- **Related ADR:** 0016 (proposed).

Allowed statuses

Rules

1. No orphan questions. Every entry has Why it matters, Where to look, Who to ask. Without these, the entry is too vague to act on. 2. No silent edits. When a question moves to ANSWERED, append the answer with a date — do not overwrite the original. 3. No drift into ADR territory. If an entry starts to resemble a decision ("We will probably use X"), it has matured into an ADR proposal; move it. 4. No bulk delete. Cleanup of ANSWERED entries happens in scheduled sweeps with the team's awareness, not silently.

Lifecycle

OPEN ----answered---> ANSWERED ----promote--> discovery-brief.md or ADR
  |
  +--parked-------> PARKED ----cited-in--> ADR Consequences

When the skills add or update entries

• adr-discovery — adds entries when a MUST cannot be confirmed; refuses to advance until the MUST is ANSWERED or PARKED.
• adr-drafting — refuses to reach the Draft phase while any MUST is OPEN. PARKED MUSTs are echoed into the ADR's Consequences.
• adr-critique — flags ADRs that reference no open-questions while obviously relying on assumptions, and ADRs that reference an OPEN question without acknowledging it as a known unknown.

Out-of-band sources

When discovery scans an external wiki, Backstage entry, TechRadar, or platform ADR set, surface what was found as an open question — never as a confirmed fact, unless the architect explicitly confirms.