/decide — Technical Decision Gate

Forces structured decision-making and creates an auditable Agent Decision Record (AgDR).

Activated role

When /decide runs, activate the Tech Lead role — they own technical decisions within their domain. For decisions that cross the architecture-review threshold (new service, new tech stack, new external integration, major data model change), escalate to the Head of Engineering before creating the AgDR.

If the decision touches auth / crypto / secrets / PII, also involve the Security Auditor for sign-off on the security implications before finalising the choice.

See .claude/rules/role-triggers.md for the full activation protocol.

Process

1. Parse the Decision Topic

Extract the decision topic from $ARGUMENTS. If unclear, ask:

What technical decision do you need to make?

2. Gather Context

Identify decision-relevant context only:

• What problem are we solving?
• What constraints exist?
• What's already in the codebase?

3. List Options

Present 2–4 options in a table:

| Option | Pros | Cons |
|--------|------|------|
| Option A | … | … |
| Option B | … | … |

4. Make the Decision

State the chosen option with justification.

5. Generate the AgDR

Create file at {project-root}/docs/agdr/AgDR-{NNNN}-{slug}.md.

Important: AgDRs live in the current project's repository, not centralised. Each project has its own docs/agdr/ folder and its own ID sequence.

Resolve the AgDR template via the portfolio helper so adopter overrides win when present:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
template=$(portfolio_resolve_template agdr.md)   # → custom-templates/agdr.md if present, else templates/agdr.md

Single-fork adopters (no portfolio block) and adopters with no override fall straight through to templates/agdr.md. Adopters who want a customised AgDR shape drop their version at <private_repo>/custom-templates/agdr.md. See templates/README.md for the path-mirroring convention.

The skeleton:

---
id: AgDR-{NNNN}
timestamp: {ISO-8601: YYYY-MM-DDTHH:MM:SSZ}
agent: {current-agent-name or "claude"}
model: {model-id from environment}
trigger: {user-prompt | hook | automation}
status: executed
---

# {short title}

> In the context of {context}, facing {concern}, I decided {decision} to achieve {goal}, accepting {tradeoff}.

## Context
{Decision-relevant context only — 2–4 bullets}

## Options Considered
| Option | Pros | Cons |
|--------|------|------|
| … | … | … |

## Decision
Chosen: **{option}**, because {justification}.

## Consequences
- {consequence 1}
- {consequence 2}

## Artifacts
- {commit / PR links when available}

6. Get the Next ID

ls docs/agdr/AgDR-*.md 2>/dev/null | sort -V | tail -1 | grep -oE 'AgDR-[0-9]+' | grep -oE '[0-9]+'
# Increment by 1, or start at 0001

7. Offer a Contrarian challenge (optional — opt-in, never forced)

A decision is a high-stakes moment. After drafting the AgDR, surface a one-line nudge offering to stress-test the call before committing:

Recorded AgDR-{NNNN}. Want Naqid (The Contrarian) to challenge this first?
Run `/challenge {topic}` — he steelmans it, then attacks hidden assumptions,
failure modes, and cheaper alternatives. Advisory — it never blocks.

Rules for the offer:

• Opt-in only. Never auto-run /challenge; the operator decides.
• Advisory only. Its verdict informs; it never vetoes or gates the decision.
• Fold the result back. If the operator runs it and the verdict shifts the call, update the AgDR's Decision / Consequences to reflect the new reasoning and note the challenge under Artifacts.

This mirrors the advisory stance in .claude/rules/role-triggers.md § "Optional advisory offer" — see .claude/skills/challenge/SKILL.md and AgDR-0078.

8. Return the Decision

Decision: {chosen option}
AgDR-{NNNN} created at docs/agdr/AgDR-{NNNN}-{slug}.md
Proceeding with: {brief action}

Rules

1. Always create an AgDR — no decision without a record
2. Y-statement required — one-line summary at the top
3. Options table required — at least 2 options compared
4. Justification required — because clause is mandatory
5. Timestamp precise — full ISO-8601 with time
6. Slug from title — lowercase, hyphens, max 50 chars
7. Offer a challenge — after drafting the AgDR, offer /challenge (opt-in, advisory, never auto-run); update the AgDR if the verdict shifts the call

---

Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.