Help us improve
Share bugs, ideas, or general feedback.
From humaninloop
Evaluates technology alternatives against criteria like fit, complexity, team familiarity, scalability, and security; scores options and documents ADRs.
npx claudepluginhub joshuarweaver/cascade-ai-ml-agents-agent-framework --plugin deepeshbodh-human-in-loopHow this skill is triggered — by the user, by Claude, or both
Slash command
/humaninloop:patterns-technical-decisionsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Provide a complete framework for technology decisions: evaluate alternatives against consistent criteria, make informed choices, and document decisions so future maintainers understand WHY choices were made.
Builds weighted decision matrices, analyzes trade-offs, and generates ADRs for architectural, technical, and process decisions like database selection or framework choice.
Generates auditable Agent Decision Records (AgDR) for technical choices like libraries, patterns, or architecture via structured process with options table. Use /decide or auto-activates on comparisons.
Documents significant architectural and technical decisions with context, alternatives, trade-offs, and consequences. Creates a decision trail for teams. Use when choosing technologies, making infrastructure decisions, or establishing standards.
Share bugs, ideas, or general feedback.
Provide a complete framework for technology decisions: evaluate alternatives against consistent criteria, make informed choices, and document decisions so future maintainers understand WHY choices were made.
1. EVALUATE → 2. DECIDE → 3. DOCUMENT
Options Best fit For posterity
For each decision point, consider 2-3 alternatives minimum.
Quick Criteria Reference:
| Criterion | Key Question |
|---|---|
| Fit | Does it solve the problem fully? |
| Complexity | How hard to implement and maintain? |
| Team Familiarity | Does the team know this tech? |
| Ecosystem | Good docs, active community? |
| Scalability | Will it grow with the project? |
| Security | Good security posture? |
| Cost | Total cost of ownership? |
| Brownfield Alignment | Fits existing stack? |
See EVALUATION-MATRIX.md for detailed criteria, scoring, and technology category comparisons.
Score options against weighted criteria. Document:
Quick Comparison Format:
| Option | Pros | Cons | Alignment | Verdict |
|---|---|---|---|---|
| Option A | + Fast, + Simple | - New dep | High | Best |
| Option B | + Familiar | - Slow | Medium | Good |
| Option C | + Feature-rich | - Complex | Low | Poor |
Record decisions in ADR format for future maintainers.
Quick Decision Record:
## Decision: [Title]
**Status**: Proposed | Accepted | Deprecated
**Context**: [Why this decision is needed]
**Decision**: [What we chose]
**Rationale**: [Why - connect to criteria]
**Trade-offs Accepted**: [What we gave up]
See DECISION-RECORD.md for full ADR format, consequences, and dependency tracking.
Decisions go in constraints-and-decisions.md with this structure:
# Constraints and Decisions: {feature_id}
## Summary
| ID | Decision | Choice | Rationale |
|----|----------|--------|-----------|
| D-001 | Auth mechanism | JWT | Stateless, scalable |
| D-002 | Session storage | PostgreSQL | Existing stack |
---
## Decision 1: [Title]
[Full decision record]
---
## Dependencies
| Decision | Depends On | Impacts |
|----------|------------|---------|
| D2 | D1 | Session table schema |
Always check existing stack first:
| Scenario | Alignment | Action |
|---|---|---|
| Existing dep solves problem | High | Prefer reuse |
| New dep, same ecosystem | Medium | Document justification |
| New dep, different ecosystem | Low | Strong justification needed |
| Conflicting with existing | None | Avoid or escalate |
Before finalizing:
Evaluation:
Documentation:
❌ "We evaluated Option A and chose it" ✅ "We compared Option A, Option B, and Option C against weighted criteria"
❌ Choosing newest technology because it's trending ✅ Require strong justification for unfamiliar dependencies over existing stack
❌ "We chose JWT because it's better" ✅ "We chose JWT because: stateless (fits our scale), team familiarity (3/4 devs), ecosystem support"
❌ Choosing Rust for a Python team without accounting for learning curve ✅ Weight team familiarity criterion appropriately in evaluation matrix
❌ Only listing positives of chosen option ✅ Explicitly document what was given up: "Trade-off: JWT requires token refresh handling"
❌ Decisions documented in isolation ✅ Map decision dependencies: "D2 (session storage) depends on D1 (auth mechanism)"
❌ Making decisions that violate project principles ✅ Check alignment with constitution before finalizing