adr-discovery

Confirm project facts with humans before writing ADR discovery briefs.

12|Updated Apr 19, 2026
One-click install
npx skills add https://github.com/janmohammadi/deep-adr --skill adr-discovery
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: adr-discovery
Source: https://github.com/janmohammadi/deep-adr/tree/main/skills/adr-discovery
Command: npx skills add https://github.com/janmohammadi/deep-adr --skill adr-discovery

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Gather project context before drafting ADRs by ensuring every fact is confirmed by a human and written to disk immediately, eliminating reliance on memory or assumptions.

Core Features & Use Cases

  • Structured back-and-forth discovery with humans to confirm every fact before recording.
  • Writes confirmed facts to docs/architecture/discovery-brief.md to maintain a living, audit-friendly brief.
  • Guides across phases: domain confirmation, component identification, relationship mapping, and ecosystem references; supports optional LikeC4 live diagram mode.
  • Park questions when information is unknown and surface them for later resolution, keeping ADR work non-blocking.

Quick Start

Start a discovery session, confirm each fact with the human, and save confirmed insights to the discovery brief.

Frequently Asked Questions about adr-discovery

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I gather context for architecture decision records in unfamiliar systems?

Gather context for architecture decision records by running a structured discovery session that requires human confirmation before recording any fact. Confirmed insights are written directly to a discovery brief, ensuring accurate documentation without relying on memory or assumptions.

What is the best way to document cross-repo architecture decisions without losing track of unknowns?

Document cross-repo architecture decisions by using an open-questions workflow that parks unknown information for later resolution. This keeps ADR work non-blocking while mapping domain, components, relationships, and ecosystem references with explicit human approval.

Can I integrate live diagrams into my ADR discovery process?

Integrate live diagrams into your ADR discovery process using the optional LikeC4 live diagram mode. This feature supports visual mapping during domain confirmation, component identification, and relationship mapping phases.

How to start a discovery session for ADR context confirmation?

Start a discovery session for ADR context confirmation by initiating a structured back-and-forth dialogue. The system guides you through phases, requiring you to confirm each fact before saving it to docs/architecture/discovery-brief.md.

Why does my ADR workflow fail when working across unfamiliar codebases?

ADR workflows fail across unfamiliar codebases due to unverified assumptions. A discovery-based approach hardens ADR decisions by requiring explicit human approval for every recorded fact, capturing ecosystem references accurately and eliminating reliance on memory.