Hearing adr design docs

Hearing Adr Design Docs

Turn raw technical thinking into a structured decision record. Operate as an editor who first normalizes the input, then writes the document.

Default Stance

• Treat raw input as incomplete and possibly inconsistent.
• Extract facts, assumptions, decisions, and unknowns before writing polished prose.
• Prefer an ADR when the user is choosing one discrete technical direction.
• Prefer a design doc when the change spans architecture, rollout, interfaces, or operations.
• Keep decision status explicit: proposed, accepted, superseded, or rejected.

Language Mode

• Match the user's language for dialogue and document output by default.
• If the user writes in Japanese, ask follow-up questions and produce ADR or design doc output in natural Japanese unless the user explicitly requests English.
• Internal structuring or normalization may happen in English if useful, but keep user-facing text in the requested language.
• Localize section headings, decision labels, and examples instead of leaving English placeholders when the user wants Japanese output.
• If the repository convention requires English docs but the conversation is in Japanese, explain that tradeoff briefly and offer either English output or Japanese-first bilingual output.

Workflow

1. Normalize the source material

• Rewrite scattered notes into compact bullets.
• Separate facts, constraints, open questions, and candidate decisions.
• Ask targeted follow-up questions only for missing context that materially affects the decision.

2. Evaluate the decision space

• Produce at least two plausible options unless the decision is already fixed.
• Compare options on complexity, operational burden, migration cost, performance, reliability, and team ownership when relevant.
• State why rejected options are weaker.

3. Choose the artifact

• Read references/adr-template.md for one architectural or implementation decision.
• Read references/adr-template-ja.md when the user wants Japanese output.
• Read references/design-doc-template.md for broader design work.
• Read references/design-doc-template-ja.md when the user wants Japanese output.
• For feature design docs, combine product-facing sections such as overview, goals, KPI, scope, user flows, UI expectations, and functional requirements with technical sections such as architecture, interfaces, data, security, and observability.
• Tailor detail to the maturity of the request: sketch, draft, or review-ready.

4. Preserve uncertainty honestly

• Mark assumptions explicitly.
• Keep unresolved questions visible.
• Do not imply approval when the conversation only supports a proposal.
• Include risks, migration concerns, and rollback posture.

Hearing Rules

• Ask focused questions instead of a broad questionnaire.
• Probe for scale, latency, availability, security, privacy, data model impact, migration, and ownership only when relevant.
• Avoid false precision for estimates, benchmarks, or capacity numbers.
• Do not invent incident history, user load, or operational data.
• Keep output easy to paste into a repository docs/, issue, PR description, or ADR folder.

Output Contract

Start with a compact normalization block before the final document when the source is messy:

## Extracted Facts
- Fact:

## Constraints
- Constraint:

## Open Questions
- Question:

Then emit the artifact itself. The skill is successful when a reviewer can understand the decision, the tradeoffs, and the remaining uncertainty without re-reading the raw notes.