adr-management
Skill1 starsChanged 3 months agoMITView on GitHub
Architecture Decision Record (ADR) creation, lifecycle management, alternative evaluation, and trade-off documentation under docs/decisions/.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- nishant-tamilselvan/AEGIStheir own version, first seen Sep 28, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- nishant-tamilselvan/AEGIS★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agentic-developmentSkill
- ci-cdSkill
- code-architectureSkill
- database-postgresqlSkill
- data-engineeringSkill
- debuggingSkill
- deep-learningSkill
- dependency-managementSkill
- deploymentSkill
- dockerSkill
- documentation-orchestratorSkill
- documentationSkill
- environment-guardrailsSkill
- frontend-react-typescriptSkill
- git-githubSkill
- machine-learningSkill
- observabilitySkill
- performance-optimizationSkill
- portfolio-readinessSkill
- project-bootstrapSkill
- project-knowledgeSkill
- python-apiSkill
- python-environmentSkill
- rag-ocr-llmSkill
- release-engineeringSkill
- reusable-componentsSkill
- security-secretsSkill
- supply-chain-securitySkill
- testing-qualitySkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Use this skill when:
- Distinctive: line 16
Do NOT use ADRs for trivial bug fixes, routine variable renames, or minor UI tweaks.
- Distinctive: line 104
NEVER hide negative consequences: Every architectural choice has trade-offs.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ADR Management Skill
1. When Should I Use This?
Use this skill when:
- Making significant, non-obvious, or difficult-to-reverse architectural decisions (Framework, Database, Vector DB, LLM provider, Package manager, Deployment host, Auth strategy, Caching, Observability, Scaling).
- Evaluating competing architectural alternatives with explicit trade-offs.
- Superseding or deprecating an earlier architectural decision.
- Maintaining the
docs/decisions/repository index.
Do NOT use ADRs for trivial bug fixes, routine variable renames, or minor UI tweaks.
2. What Should I Inspect First?
- Existing ADRs: Inspect
docs/decisions/to identify previous decisions and the next sequential ID (e.g.0001,0002). - Current Constraints: Technical limitations, budget, hosting environment, compliance, or team skillset.
- Competing Options: Identify at least two viable alternatives to the chosen approach.
3. What Workflow Should I Follow?
Identify Significant Architecture Choice
↓
Assign Next Sequential Number (docs/decisions/NNNN-title.md)
↓
Draft Context & Problem Statement
↓
List Concrete Alternatives Considered with Pros & Cons
↓
Record Decision & Justification
↓
Document Positive & Negative Consequences
↓
Define Explicit Verification / Validation Criteria
↓
Update docs/decisions/README.md Index & MCP Codebase MemoryCanonical ADR Template
# ADR-0001: Selection of FAISS and SentenceTransformers for Embedded RAG
## Status
Accepted
## Date
2026-08-14
## Context
DocMind requires real-time semantic retrieval over extracted OCR PDF text chunks. We need sub-50ms query latency, zero external API costs, and full operational support inside self-hosted Docker containers without relying on external cloud vector databases.
## Alternatives Considered
### Alternative 1: Pinecone / Managed Cloud Vector DB
* **Pros**: Fully managed, auto-scaling, built-in metadata filtering.
* **Cons**: Introduces external network latency (100-300ms roundtrip), requires recurring monthly subscription, fails in air-gapped/offline Docker environments.
### Alternative 2: PostgreSQL + pgvector
* **Pros**: Single unified database for relational tables and embeddings.
* **Cons**: Higher memory usage for index maintenance inside small container instances; slightly higher query latency than pure C++ FAISS.
### Alternative 3: FAISS (Facebook AI Similarity Search) + SentenceTransformers (Chosen)
* **Pros**: In-memory C++ execution provides sub-10ms similarity search; runs 100% locally inside Docker; zero external subscription costs.
* **Cons**: Index must be serialized to disk or rebuilt upon container restarts; memory is bounded by single-node RAM.
## Decision
We choose **FAISS** (`IndexFlatIP` with normalized embeddings) paired with `sentence-transformers/all-MiniLM-L6-v2`.
## Consequences
* **Positive**: Blazing fast retrieval, zero external dependencies, reproducible local testing.
* **Negative / Mitigations**: We must implement local index disk persistence in `storage/vectorstore/` and reload on startup via FastAPI lifespan handlers.
## Verification
* Unit tests in `tests/unit/test_rag.py` must verify retrieval latency < 50ms across 1,000 indexed chunks.
* Docker container must start and query without internet access.4. What Decisions Should I Make?
| ADR Lifecycle Status | Definition |
| Proposed | Under active discussion or prototype evaluation. |
| Accepted | Approved and actively being implemented or deployed. |
| Superseded | Replaced by a newer decision (must reference Superseded by ADR-XXXX). |
| Deprecated | No longer relevant or actively phased out. |
5. What Should I Avoid?
- NEVER write ADRs after the fact without documenting alternatives: The primary value of an ADR is explaining why alternatives were rejected.
- NEVER hide negative consequences: Every architectural choice has trade-offs; document them honestly.
- NEVER include secrets, passwords, or internal URLs in ADRs.
6. How Should I Verify Success?
# 1. Verify ADR exists and has all required sections
python -c "
import os, glob
adrs = glob.glob('docs/decisions/*.md')
required = ['Status', 'Context', 'Decision', 'Alternatives Considered', 'Consequences', 'Verification']
for adr in adrs:
content = open(adr, encoding='utf-8').read()
for section in required:
assert section in content, f'Missing {section} in {adr}'
print(f'All {len(adrs)} ADRs validated with complete structure.')
"Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

