Apply Decisions

---
name: apply-decisions
description: Canonical algorithm for consuming DECISIONS_CONTEXT index — scan index, identify relevant entries, Read full bodies on demand, cite verbatim IDs inline.
user-invocable: false
allowed-tools: Read
---

# Apply Decisions

Canonical consumer algorithm for the `DECISIONS_CONTEXT` index passed by orchestrators. The index lists each ADR/PF entry with ID, truncated title, status, and area — not the full body. Use this skill to surface the right decisions and pitfalls for your task without loading the entire corpus.

## Iron Law

> **VERBATIM IDs ONLY — NEVER FABRICATE**
>
> Cite only IDs that appear verbatim in DECISIONS_CONTEXT. If an ADR/PF ID is not
> in the index, do not cite it. If an entry looks relevant but you haven't Read its
> full body, do not cite it. Fabricated citations are worse than no citations.

---

## 5-Step Algorithm

### Step 1: Scan the index

Read through all entries in `DECISIONS_CONTEXT`. The index format is:

```
Decisions (N):
  ADR-001  Title truncated to 60 chars  [Active]
  ADR-002  Another decision             [Active]

Pitfalls (M):
  PF-004  Background hook god scripts  [Active]  —  src/assets/scripts/hooks/foo.cjs
  PF-011  DECISIONS_CONTEXT fan-out    [Active]  —  src/assets/commands/...

ADR-NNN entries live in {worktree}/.devflow/learning/decisions.md
PF-NNN  entries live in {worktree}/.devflow/learning/pitfalls.md
Read the relevant file and locate the matching `## ADR-NNN:` or `## PF-NNN:` heading for the full body.
```

### Step 2: Identify plausibly-relevant entries

From the index, identify entries whose title or area plausibly overlaps with:
- The files you are modifying or reviewing
- The category of issue you are addressing (e.g., error handling, hook scripts, JSON parsing)
- The architectural area of your change

Titles are truncated to 60 characters — if a truncated title looks relevant, proceed to Step 3.

### Step 3: Read the full body

For each plausibly-relevant entry, use the Read tool to open the decisions file listed in the `DECISIONS_CONTEXT` footer and locate the matching `## ADR-NNN:` or `## PF-NNN:` heading. Read the full section to confirm relevance and understand the decision or pitfall completely.

**The footer is the single source of truth for file paths.** Never substitute hardcoded paths — the footer resolves to the correct worktree, which may differ from your cwd in multi-worktree flows.

```
Use the exact paths from the DECISIONS_CONTEXT footer, e.g.:
  {worktree-from-footer}/.devflow/learning/decisions.md   → find ## ADR-NNN: heading
  {worktree-from-footer}/.devflow/learning/pitfalls.md    → find ## PF-NNN: heading
```

Only cite an entry after you have read its full body and confirmed it applies.

### Step 4: Cite inline

When applying a prior decision, cite as `applies ADR-NNN` in your reasoning or output. When avoiding a known pitfall, cite as `avoids PF-NNN`. Place citations in the Reasoning column of decision tables, in inline comments, or in your structured output — wherever your agent's output format captures rationale.

### Step 5: Use verbatim IDs only

Cite only IDs that appear verbatim in `DECISIONS_CONTEXT`. Do not guess at IDs that might exist. Do not construct IDs from memory. If no entry is clearly relevant, skip citation entirely — silence is correct when nothing applies.

---

## Worked Example

**Scenario**: Reviewing `src/assets/scripts/hooks/background-learning` for issues.

1. **Scan** — Index shows `PF-004  Background hook god scripts  [Active]  —  src/assets/scripts/hooks/foo.cjs`
2. **Identify** — Area field includes `src/assets/scripts/hooks/` which overlaps with the file under review
3. **Read** — Open the pitfalls file at the path given in the DECISIONS_CONTEXT footer (e.g., `<worktree>/.devflow/learning/pitfalls.md`), find `## PF-004:` section, read full body
4. **Cite** — If the file shows signs of the god-script pattern, note `avoids PF-004` in reasoning
5. **Verbatim** — ID `PF-004` appeared in the index; citation is valid

---

## Skip Guard

When `DECISIONS_CONTEXT` is empty, `(none)`, or not provided: skip this skill entirely. Do not attempt to load decisions files independently. Do not speculate about what decisions or pitfalls might exist.

---

## Citation Format Reference

| Situation | Citation |
|-----------|----------|
| Applying a prior architectural decision | `applies ADR-NNN` |
| Avoiding a known pitfall | `avoids PF-NNN` |
| Entry not in index | (no citation — silence is correct) |
| Entry in index but not read yet | (no citation — read first) |