| 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.
- Scan — Index shows
PF-004 Background hook god scripts [Active] — src/assets/scripts/hooks/foo.cjs
- Identify — Area field includes
src/assets/scripts/hooks/ which overlaps with the file under review
- 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
- Cite — If the file shows signs of the god-script pattern, note
avoids PF-004 in reasoning
- 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) |
