tranhieutt/architecture-decision
.claude/skills/architecture-decision/SKILL.md
Documents architectural and technology decisions as Architecture Decision Records (ADRs). Use when a significant tech-stack choice, design pattern, or infrastructure decision needs to be recorded with context and rationale.
$ install --global
skillsauthnpx skillsauth add tranhieutt/software_development_department architecture-decisionInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 15, 2026, 11:47 PM11.8s1 file scanned
SKILL.md
- name:
- architecture-decision
- description:
- Documents architectural and technology decisions as Architecture Decision Records (ADRs). Use when a significant tech-stack choice, design pattern, or infrastructure decision needs to be recorded with context and rationale.
- argument-hint:
- [title]
- user-invocable:
- true
- allowed-tools:
- Read, Glob, Grep, Write
- context:
- fork
- agent:
- cto
- effort:
- 4
- when_to_use:
- When needing to make a technology decision and record the underlying reasoning
When this skill is invoked:
-
Determine the next ADR number by scanning
docs/architecture/for existing ADRs. -
Gather context by reading related code and existing ADRs.
-
Guide the user through the decision by asking clarifying questions if the title alone is not sufficient.
-
Generate the ADR following this format:
# ADR-[NNNN]: [Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
## Date
[Date of decision]
## Context
### Problem Statement
[What problem are we solving? Why does this decision need to be made now?]
### Constraints
- [Technical constraints]
- [Timeline constraints]
- [Resource constraints]
- [Compatibility requirements]
### Requirements
- [Must support X]
- [Must perform within Y budget]
- [Must integrate with Z]
## Decision
[The specific technical decision made, described in enough detail for someone
to implement it.]
### Architecture Diagram
[ASCII diagram or description of the system architecture this creates]
### Key Interfaces
[API contracts or interface definitions this decision creates]
## Alternatives Considered
### Alternative 1: [Name]
- **Description**: [How this would work]
- **Pros**: [Advantages]
- **Cons**: [Disadvantages]
- **Rejection Reason**: [Why this was not chosen]
### Alternative 2: [Name]
- **Description**: [How this would work]
- **Pros**: [Advantages]
- **Cons**: [Disadvantages]
- **Rejection Reason**: [Why this was not chosen]
## Consequences
### Positive
- [Good outcomes of this decision]
### Negative
- [Trade-offs and costs accepted]
### Risks
- [Things that could go wrong]
- [Mitigation for each risk]
## Performance Implications
- **CPU**: [Expected impact]
- **Memory**: [Expected impact]
- **Load Time**: [Expected impact]
- **Network**: [Expected impact, if applicable]
## Migration Plan
[If this changes existing code, how do we get from here to there?]
## Validation Criteria
[How will we know this decision was correct? What metrics or tests?]
## Related Decisions
- [Links to related ADRs]
- [Links to related design documents]
-
Save the ADR to
docs/architecture/adr-[NNNN]-[slug].md. -
Cross-post a summary entry to
docs/technical/DECISIONS.mdby appending the following block at the bottom of the file (above the closing comment line if present):
## ADR-[NNN]: [Title]
**Date**: [Date]
**Status**: Accepted
**Deciders**: [Name(s) / @agent]
**Detailed ADR**: [docs/architecture/adr-[NNNN]-[slug].md](../architecture/adr-[NNNN]-[slug].md)
### Context
[One paragraph summary of the problem]
### Decision
[One paragraph summary of the decision and primary reason]
### Consequences
- **Positive**: [Key benefit]
- **Negative**: [Key trade-off accepted]
Also update the Decision Index table in docs/technical/DECISIONS.md by replacing the placeholder row (or appending a new row) with:
| ADR-NNN | [Title] | Accepted | [Date] | [Decider] |
Protocol
- Question: Clarify title, context, constraints, and alternatives if the argument alone is insufficient
- Options: Alternatives Considered section — presents and evaluates 2+ options before deciding
- Decision: User confirms the decision to record before ADR is drafted
- Draft: Full ADR shown in conversation before saving
- Approval: "May I write to
docs/architecture/adr-[NNN]-[slug].md?"
Output
Deliver exactly:
- ADR file saved to
docs/architecture/adr-[NNNN]-[slug].md - Decision Index entry appended to
docs/technical/DECISIONS.md - Summary in 2 sentences: what was decided and why
- Top risk to watch from the Consequences section
Related Skills
tranhieutt/visual-engineer
testing
VerifiedTrustedCommunity
Generates high-fidelity architecture diagrams, sequence flows, and component maps for SDD projects. Use when finalizing a design phase, documenting system architecture, or visualizing agentic workflows. Default style: Style 6 (Claude Official).
60SKILL.mdUpdated Apr 15, 2026
tranhieutt/vector-database-engineer
data-ai
VerifiedTrustedCommunity
Provides vector database and semantic search patterns for Pinecone, Weaviate, Qdrant, Milvus, and pgvector in RAG and recommendation systems. Use when implementing vector search or when the user mentions vector database, semantic search, embeddings, or similarity search.
60SKILL.mdUpdated Apr 15, 2026
tranhieutt/update-codemap
development
VerifiedTrustedCommunity
Updates docs/technical/CODEMAP.md by scanning the current codebase structure. Run after a significant feature merge, refactor, or when CODEMAP feels stale.
60SKILL.mdUpdated Apr 15, 2026
tranhieutt/unfreeze
development
VerifiedTrustedCommunity
Unlocks the codebase after a release freeze or incident freeze period to resume normal development. Use when a freeze period ends or when the user mentions unfreezing or lifting the code freeze.
60SKILL.mdUpdated Apr 15, 2026