architecture-decision-record
Extracts key architectural decisions from technical-requirements.yaml and formalizes them as individual ADR markdown files in an adrs/ directory. Each ADR captures context, the decision made, alternatives considered, and consequences — creating a durable record of why the system is built the way it is.
How do I install this agent skill?
npx skills add https://github.com/validkeys/sherpy --skill architecture-decision-recordIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The architecture-decision-record skill is a documentation tool that formalizes architectural choices. It carries a low risk of indirect prompt injection as it processes user-provided YAML requirements to generate file system paths and ADR content without explicit sanitization or input validation.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Architecture Decision Record
Extracts key architectural decisions from technical-requirements.yaml and formalizes each one as a standalone ADR file. ADRs document why the system is built the way it is, not just what was chosen — making them essential for onboarding, audits, and revisiting trade-offs.
Prerequisites
{base_directory}/requirements/technical-requirements.yaml(output from/technical-requirements-interview)
Usage
/architecture-decision-record [base-directory]
If no directory is provided, auto-detect by looking for requirements/technical-requirements.yaml in the current directory.
If not found, prompt the user: "Where are your requirements documents located?"
Wait for the user to provide a path before proceeding. Store as base_directory.
Process
Step 1: Determine Base Directory and Load Technical Requirements
If no directory parameter was provided, check if requirements/technical-requirements.yaml exists in the current directory.
- If found, use current directory as
base_directory - If not found, prompt: "Where are your requirements documents located?" and wait for user response
Once base_directory is determined, read {base_directory}/requirements/technical-requirements.yaml and identify every decision point. Look in these sections:
architecture— patterns, frameworks, structural choicestechnology_stack— language, runtime, major libraries, databasesdata_model— storage engine choice, schema design decisionsapi_design— REST vs GraphQL vs RPC, versioning strategysecurity— auth mechanism, token strategy, encryption approachtesting— testing strategy, coverage targets, toolingdeployment— hosting, CI/CD pipeline, containerizationtrade_offsandopen_questions— explicitly flagged decisions
Collect each decision as a candidate ADR. A decision qualifies if:
- It involves a meaningful choice between alternatives, OR
- It has notable consequences for the system's future flexibility, OR
- It was explicitly flagged as a trade-off or open question
Step 2: Identify Alternatives
For each candidate decision, reason about what the realistic alternatives were. Derive these from:
- The
trade_offssection of the technical requirements (if present) - Common alternatives for the chosen technology/pattern
- Any "options considered" language in the requirements
If no alternatives are inferable, note "alternatives not documented" rather than fabricating them.
Step 3: Assign ADR IDs and Titles
Number ADRs sequentially starting at ADR-001. Titles should be brief and declarative:
- Good:
Use PostgreSQL as the primary data store - Bad:
Database decision
Group related decisions logically (e.g., all auth decisions before all deployment decisions).
Step 4: Write ADR Files
Create the directory structure:
mkdir -p {base_directory}/architecture/adrs
Write one file per ADR: {base_directory}/architecture/adrs/ADR-NNN-kebab-case-title.md
Each file follows this format:
The ADR document includes: header (ADR-NNN: Title, Status, Date, Source), and four required sections: Context (problem description), Decision (the choice made), Alternatives Considered (table of options ruled out), and Consequences (Positive, Negative/Trade-offs, Risks).
See references/adr-document-spec.md for the complete ADR document specification with all sections and formatting rules.
See references/example-ADR-001.md and references/example-ADR-003.md for full examples.
Step 5: Write INDEX.md
Create {base_directory}/architecture/adrs/INDEX.md as a summary table:
The index includes a single table with columns: ID (link), Title, Status, Date.
See references/adr-index-spec.md for the complete INDEX specification.
See references/example-INDEX.md for a full example.
Step 6: Gap Analysis
Report inline after generating all files:
## ADR Gap Analysis
**Project:** [name]
**ADRs Generated:** [n]
**Decision Areas Covered:**
[✓ / ✗] Architecture / structural patterns
[✓ / ✗] Technology stack
[✓ / ✗] Data storage
[✓ / ✗] API design
[✓ / ✗] Security / authentication
[✓ / ✗] Testing strategy
[✓ / ✗] Deployment / infrastructure
**Open Questions carried forward:** [n]
[List any open_questions from technical-requirements.yaml that could not yet be
formalized as Accepted ADRs — these are candidates for future ADRs.]
**Recommendations:** [none / list]
Output Format
{base_directory}/architecture/adrs/
INDEX.md
ADR-001-[title].md
ADR-002-[title].md
...
Example Output
See references/ for sample ADR files (ADR-001, ADR-003) and an INDEX.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/validkeys/sherpy/architecture-decision-record">View architecture-decision-record on skillZs</a>