JosiahSiegel/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.

| Wrong | Right | |---|---| | "Your system uses Postgres and Redis." | "I see pg and ioredis in package.json. Is Postgres your primary store? (yes / no / unsure)" | | "Component A talks to component B." | "I see a fetch from A to B in src/a/client.ts. Does A depend on B? (yes / no)" |

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

| State | Where it lives | Allowed to drive a decision? | |---|---|---| | CONFIRMED | discovery-brief.md | Yes | | FROM CODE, UNCONFIRMED | open-questions.md | No | | UNKNOWN | open-questions.md | No | | PARKED | open-questions.md (with reason) | No — must be noted in ADR Consequences |

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:

| MUST | Confirmed when… | |---|---| | Domain | Architect has stated what the system does and for whom | | Architectural characteristic under pressure | Architect named the quality being optimized (latency / cost / availability / etc.) and the specific number or condition forcing the decision | | ≤5 components in scope | Architect confirmed each by name, with a one-line description | | Related ADRs classified | Each existing ADR classified or explicitly dropped | | Named decision-maker | Specific human(s) — not "the team," not "leadership" |

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