with one click
df-decisions
// Encapsulates the DECISIONS: tagging protocol for architectural decision documentation in task outputs
// Encapsulates the DECISIONS: tagging protocol for architectural decision documentation in task outputs
| name | df-decisions |
| description | Encapsulates the DECISIONS: tagging protocol for architectural decision documentation in task outputs |
The DECISIONS: line documents architectural choices and key assumptions made during task execution. This protocol standardizes how agents capture non-obvious decisions so they can be extracted and archived incrementally.
Place the DECISIONS: line in your task output as the second-to-last line, immediately before TASK_STATUS::
DECISIONS: [TAG] {decision} โ {rationale} | [TAG] {decision2} โ {rationale2}
TASK_STATUS:pass
Multiple decisions are separated by | (space-pipe-space). Each decision is atomic; only valid entries are written to .deepflow/decisions.md.
| Tag | Use When | Example |
|---|---|---|
[APPROACH] | You chose X over Y for architectural/design reasons | [APPROACH] Used immutable state snapshots over reactive refs โ enables clean recovery and testability |
[PROVISIONAL] | Solution works now but won't scale or needs revisit | [PROVISIONAL] Hardcoded registry; refactor to dynamic discovery when >10 providers exist |
[ASSUMPTION] | You assumed X is true; if wrong, Y breaks | [ASSUMPTION] Assumed file format never changes; if schema evolves, migration logic required |
[FUTURE] | You deferred X because Y; document revisit trigger | [FUTURE] Deferred caching because auth service not finalized; add when auth.md ships |
[UPDATE] | You changed a prior decision from X to Y | [UPDATE] Changed from sync API to async to avoid blocking UI renders (discovered via profiling) |
Include DECISIONS: when:
medium or high (non-mechanical work)Skip DECISIONS: when:
low (mechanical extraction, formatting, simple bug fixes)Validation rule: If a task has effort โฅ medium and no DECISIONS: line appears in your output, the curator will emit SALVAGEABLE (indicating potential architectural choices were not documented).
Each decision entry in .deepflow/decisions.md MAY carry an inline Files: tag listing relative repo paths the decision concerns. This enables bin/decisions-index.js to retrieve prior decisions and spike results touching a given file set during impact analysis.
- [TAG] description โ rationale Files: [path/to/file.ts, path/to/other.ts]
The Files: tag is placed at the end of the bullet, after the rationale, separated by two spaces. The paths are relative to the repo root, comma-separated, enclosed in square brackets.
- [APPROACH] Used line-scan regex over AST parsing โ simpler, zero deps, sufficient for flat markdown Files: [bin/decisions-index.js]
- [PROVISIONAL] Hardcoded max_retries=3; bump when traffic patterns change Files: [src/commands/df/execute.md, src/skills/df-decisions/SKILL.md]
Files:Omit the Files: tag when the decision is purely conceptual or spans the entire codebase with no specific file targets. Entries without a Files: tag are silently skipped by the query utility (no error).
The curator runs decision extraction after each ratchet pass:
DECISIONS: line from agent output[TAG] where TAG โ {APPROACH, PROVISIONAL, ASSUMPTION, FUTURE, UPDATE}[TAG] description โ rationale (must contain โ separator).deepflow/decisions.md under dated section:
### 2026-04-21 โ spec-name
- [APPROACH] description โ rationale
- [APPROACH] description with files โ rationale Files: [src/file.ts]
DECISIONS: [APPROACH] Inline config over external YAML โ reduces deployment complexity | [PROVISIONAL] Hardcoded max_retries=3; bump when traffic patterns change | [FUTURE] Defer distributed tracing until observability service exists
DECISIONS: [ASSUMPTION] Assumes event ordering is guaranteed by broker; add dedup if semantics change
DECISIONS: (omitted for low-effort task)
The โ rationale portion should be concise (1โ2 sentences) answering why:
[APPROACH]: Why X is better than alternatives[PROVISIONAL]: What condition triggers revisit[ASSUMPTION]: What breaks if assumption is violated[FUTURE]: What blocker prevents doing it now; what unblocks it[UPDATE]: What caused the change in direction.deepflow/decisions.md[HINT] Download the complete skill directory including SKILL.md and all related files