Skip to content

dvy1987/agent-loom / .agents/skills/architectural-decision-log

architectural-decision-log

Verified

Capture the "why" behind technical choices to prevent architectural drift. Load when the user makes a major technical decision, chooses a library/framework, defines a system boundary, or changes a core architectural pattern. Also triggers on "record a decision", "write an ADR", "why did we do this", "document this architectural choice", or "architectural decision record". Supports `SYNTHESIS=true` mode for retrospective ADR backfill from observed repo state — used by `retroactive-project-setup` and any future backfill skill. Essential for long-term project maintainability and agent alignment.

FileKindSize
SKILL.mdskill md9.3 KB
references/examples.mdmarkdown3.2 KB

references/examples.md

View on GitHub
# Architectural Decision Log (ADL) — Full Worked Examples

Skill: `architectural-decision-log` | Enriched from SKILL.md (improve-skills pass, SKIP_RESEARCH).

## Example 1 — Documented workflow

**Input:** We just decided to use SQLite instead of PostgreSQL for our internal tool. Record this as an ADR.

**Output:**
```
**ADR-005: Use SQLite for Internal Tool Database**
**Date:** 2026-04-12 | **Status:** Accepted

**Context:**
The tool is single-user, deployed locally, with <10K records. We need a database that requires zero infrastructure setup and ships as a single file for easy backup and portability.

**Decision:**
Use SQLite as the primary database via sync SQLAlchemy.

**Alternatives Considered:**
- **PostgreSQL:** Full ACID, rich query support, excellent tooling. Rejected: requires a running server process, Docker or system install, connection management — all unnecessary overhead for a single-user local tool.
- **JSON flat files:** Zero dependencies, human-readable. Rejected: no query capability, no schema enforcement, concurrent write corruption risk, does not scale past ~1K records without performance degradation.

**Consequences:**
- ✓ Zero infrastructure — database is a single `.db` file
- ✓ No connection pooling, no server process, instant setup
- Tradeoff: No concurrent write support — acceptable for single-user but blocks future multi-user
- Tradeoff: Limited full-text search — may need FTS5 extension if search becomes critical
- If we ever need multi-user, this decision must be superseded (migration to PostgreSQL)

ADR recorded: ADR-005: Use SQLite for Internal Tool Database
Number: 005
Status: Accepted
Alternatives considered: 2
Critical consequences: No concurrent writes, limited FTS
Ready for: implementation
```

## Example 2 — Step-by-step execution

**Input:** "Run `architectural-decision-log` on [concrete task]"

**Agent actions:**
1. Identify the Decision
2. Gather Context & Options
3. Draft the ADR
4. Link to Previous Decisions
5. Present and Save
6. Memory Checkpoint (Mandatory)

## Example 3 — Gotcha application

**Input:** Task hits a non-obvious edge case

**Apply:**
- The highest-value ADR content is the rejected alternatives with rejection reasons — not the chosen option. Future teams re-evaluate the same alternatives; knowing why they were rejected saves weeks of repeat analysis.
- ADRs written retrospectively produce confabulated reasoning. Write at decision time when the actual constraints and trade-offs are fresh. A rough ADR today beats a polished one written from memory next month.
- "Accepted" is not permanent. Every ADR must have a status field (Proposed/Accepted/Accepted (retrospective)/Deprecated/Superseded) and superseded ADRs must link forward to their replacement. Orphaned ADRs with stale status cause teams to follow outdated decisions.
- `SYNTHESIS` mode is honest, not confident. Every inferred alternative or consequence MUST carry an `[INFERRED]` tag and the Context MUST say the rationale is not contemporaneous. Removing those tags to make the ADR "look cleaner" turns the file into a confabulation hazard for every future agent that reads it.

---

See `SKILL.md` for hard rules and verification checklist.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall