decision-capture — record agent decisions for audit Skill

decision-capture — record agent decisions for audit

Why this exists. Agent reasoning is ephemeral: a decision's rationale + the sources it was based on vanish at session end unless written down at decision-time. A spec-driven / ai-driven project sees agents drift from canonical SPECs (e.g. BR/FR/NFR/ADR ids); the team needs to audit why. This skill is the in-session write-path of the ASH decision-audit extension (docs/governance/ash-schema.md §17).

When to capture (trigger)

Call agentic-decide right after you make a non-trivial decision — one that:

shapes product / architecture / data-model / code structure, AND
a reviewer could reasonably question later, OR
touches a SPEC (BR-/FR-/NFR-/ADR-) or the manifesto, OR
deviates from a prototype / spec / manifesto (always capture these — spec_alignment=divergent).

Heuristic: if you'd write a sentence starting "I decided X because Y" — capture it.

When NOT to capture (skip)

Trivial: typos, formatting, mechanical edits, read-only inspection, running tests/builds.
Operator directives (what the human asked) — those are reconstructed by the ASH Stop subagent, not this skill. This skill is for the agent's own decisions.

How to capture

agentic-decide \
  --decision "Use column-based RLS, not schema-per-tenant" \
  --rationale "Lower migration cost; tenant_id filter sufficient for pilot scale" \
  --source spec:ADR-006:cited \
  --source file:docs/manifesto/PROJECT-MANIFESTO.md:attended \
  --source variable:tenant_id:cited \
  --spec-ref ADR-006 --spec-ref NFR-003 \
  --spec-alignment aligned \
  --confidence high

--source TYPE:REF:INFL (repeatable) — what you based the decision on. INFL ∈ attended (read + shaped your choice) · cited (explicitly referenced) · ignored (saw but deliberately didn't use). TYPE ∈ spec|file|link|field|variable|tool|transcript|mcp. URLs with colons are fine.
--spec-alignment ∈ aligned|divergent|unverified — the drift signal. Be honest: if you deviate from a spec, mark divergent and say why in --rationale. This is the field the operator audits.
--confidence ∈ high|medium|low.
One call per decision; ids auto-increment (DEC-1, DEC-2, …) per session.

Captured records stage to .claude/audit/staging/<session>.decisions.jsonl, then the decide-merge.sh Stop hook deterministically folds them into the session's journal decisions[].

How it gets audited (downstream)

The operator / a reviewer runs:

agentic-decisions                              # table of all decisions
agentic-decisions --filter spec_alignment=divergent   # the drift query
agentic-decisions --filter spec_ref=ADR-006 --sort alignment
agentic-decisions --output json | jq '…'       # [C06] machine output

Discipline (anti-theater)

Never fabricate a decision or a source. If you didn't base it on something, omit --source.
Honest alignment: don't mark aligned to look good — a divergent capture with a clear rationale is exactly the signal the team wants.
Role-types only in free-text (no PII real-names). No secrets in --rationale/--source.

Refs

Contract: docs/governance/ash-schema.md §17 (v1.6.0 decision-audit extension)
Tools: agentic-decide · skills/agentic-session-harness/hooks/decide-merge.sh · agentic-decisions
Layer-1 schema: docs/governance/agentic-session-harness-spec.md (frozen-17; promotion candidate)
External grounding: OpenTelemetry GenAI agent.output.source.influence; otel-agent-provenance Tier-1; Coverge "AI audit trail" (reasoning ephemerality).

Agent Skills: decision-capture — record agent decisions for audit

Install this agent skill to your local