/dr-plan

Overview

/dr-plan generates a detailed implementation plan in datarim/tasks.md, following the Enhanced Design Process (Phases 4-6). It resolves the target task, breaks work into concrete steps, defines interfaces, models threats, captures live fixtures for external tool output, and produces a plan ready for execution.

Usage

/dr-plan

What It Does

1. Task Resolution — applies the Task Resolution Rule to determine which task is being planned (from argument or disambiguation when multiple tasks are active).
2. Analyze Context — reads tasks.md, activeContext.md, and any PRD files from datarim/prd/.
3. Strategist Gate (mandatory for L3-4, optional for L2) — evaluates value, risk, and cost. If the strategist recommends a pivot or cheaper alternative, presents it before proceeding.
4. Detailed Design (Phase 4) — component breakdown listing every modified and new file, interface design with function signatures and API contracts, data flow tracing, and security threat modeling.
5. Implementation Plan (Phase 5) — updates tasks.md with security summary, architecture impact, detailed design (API, DB, config), implementation steps, test plan, rollback strategy, and validation checklist.
6. Technology Validation — documents stack selection, verifies dependencies and build configuration.
7. Installer / Deploy-Script Audit (mandatory when plan touches install.sh, sync scripts, or deploy tools) — greps the file-type filter in the target script and lists every supported extension in the plan. If the plan introduces files with an extension the installer does not handle, either extends the filter or records the gap as a known limitation with a follow-up backlog item.
8. Research Kill-Criteria Checkpoint (for comparative tasks) — after research but before mechanical testing, evaluates whether evidence alone eliminates candidates (deprecated, stale, wrong license). Candidates failing kill-criteria skip testing entirely.
9. Planning Hygiene — all aggregate counts in the plan (total deferred, files touched, threats) must be derived from source tables and cite them inline. Freehand summary numbers are prohibited.
10. Fixture Capture (mandatory when the plan parses CLI / subprocess / API responses) — captures a real sample during /dr-plan and commits it to datarim/tasks/{TASK-ID}-fixtures.md. Prefers machine-readable output (--json, --output-format stream-json) over human-text parsing.

CLI Agent Exit Code Pattern

Many CLI agents (Claude Code, Cursor, likely Gemini/Codex) return exit code 0 even when the JSON output contains is_error: true. When capturing fixtures, always capture both success and error cases. Parsers must check is_error/subtype in JSON, not rely on exit codes.

Arguments

None. Operates on the currently active task (resolved via Task Resolution).

Output

Updates: datarim/tasks.md with the full design document. May create: datarim/tasks/{TASK-ID}-fixtures.md.

Plan Structure

The plan includes: overview, security summary (attack surface, risks), architecture impact, detailed design (components, API, database), security design (threat model, controls), implementation steps, test plan (unit/integration/security), rollback strategy, validation checklist, and next steps.

Transition Checkpoint

Before moving to the next stage, verifies:

• Requirements clearly documented
• Components and affected files identified
• Installer/deploy-script content-type audit done (if applicable)
• Live fixture captured if the plan parses any external tool output
• All aggregate counts derived from source tables (not freehand)
• Definition of Done is testable and explicit
• Boundaries stated (what we do not do)
• Technology stack validated
• Rollback strategy viable

Example Session

> /dr-plan

Task Resolution: AUTH-0001 (Level 3)

Reading context...
  PRD: PRD-authentication.md

Strategist Gate:
  Value: High (core feature, blocks 3 other tasks)
  Risk: Medium (OAuth complexity, token management)
  Cost: 2-3 days estimated
  Verdict: Proceed as planned

Fixture Capture:
  Captured: Claude CLI success + error output
  Saved: datarim/tasks/AUTH-0001-fixtures.md
  Note: exit code 0 in both cases — parser uses is_error field

Generating plan...
  Components: 8 files (4 new, 4 modified)
  API endpoints: 5
  DB migrations: 2
  Test cases: 14

Plan written to datarim/tasks.md
Next step: /dr-do or /dr-design

Related Commands

• /dr-prd — previous stage: requirements
• /dr-design — deep design exploration for L3-4
• /dr-do — next stage: implementation