rdc-preplan

name: rdc:preplan description: "Usage rdc:preplan <topic> — Before committing to an architecture, research unknowns first. Codebase scan + web search, no code written, no work items created. Output feeds rdc:plan. Use for open-ended approach questions."

⚠️ OUTPUT CONTRACT (READ FIRST): guides/output-contract.md Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps. One checklist upfront, updated in place, shown again at end with a 1-line verdict.

If dispatching subagents or running as a subagent: read {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md first (fallback: {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md).

Sandbox contract: This skill honors RDC_TEST=1 per guides/agent-bootstrap.md § RDC_TEST Sandbox Contract. This skill is read-only and produces only local file writes — no destructive external calls to short-circuit.

rdc:preplan — Research Before Planning

When to Use

• Starting a new feature area you haven't built before
• Need to understand how best-in-class projects solve a problem
• Codebase has unknowns that need mapping before planning
• Project lead says "research", "look into", "what's the best way to", "how do others do"
• Called by rdc:overnight before planning an epic with no existing tasks

Arguments

• rdc:preplan <topic> — interactive research session
• rdc:preplan <topic> --unattended — silent mode for overnight builds

Procedure

1. Parse the topic from user input or epic title/description.

   • Interactive: if vague, ask ONE clarifying question before proceeding
   • Unattended: infer from the epic title + description — never pause to ask

2. Web research — search for current (2025-2026) best practices:

   • How do major projects solve this?
   • What tools/libraries exist?
   • What are the common tradeoffs?

3. Codebase analysis — what do we already have?

   • Search relevant packages for existing code
   • Check .rdc/research/ for prior research on this topic (fallback: .rdc/research/)
   • Check docs/archive/ for historical work
   • Research agents should read relevant guides from .rdc/guides/ (fallback: .rdc/guides/)
   • Check work items for related epics
   • Read relevant CLAUDE.md files

4. Best-in-class comparison — create a comparison table: | Approach | Pros | Cons | Fit for Us |

5. Surface unknowns — what questions remain unanswered?

6. Write research doc to .rdc/research/<topic-slug>.md (fallback: .rdc/research/<topic-slug>.md if .rdc/ does not exist):

   # Research: <Topic>
   > Generated: <date> | Requested by: Project Lead
   
   ## Question
   ## What We Already Have
   ## Best-in-Class Analysis
   ## Comparison Table
   ## Unknowns & Open Questions
   ## Recommendation (preliminary — not a decision)
   

7. Report results:

   • Interactive: summarize findings. Do NOT create epics or write code.
   • Unattended: skip summary, emit status block only:

     PREPLAN_STATUS: { topic, doc_path, unknowns_count, recommendation_confidence: "high|medium|low" }
     

Unattended Escalation

When --unattended and recommendation_confidence is "low" (≥5 unresolved unknowns, or no clear best-fit approach exists), escalate via the advisor tool rather than stopping. Provide the advisor with: topic, unknowns list, comparison table. Resume with advisor's direction if given. If advisor cannot resolve, log and skip to next step.

Rules

• Output is a RESEARCH DOC, not a plan
• Do not make architectural decisions — surface options with tradeoffs
• Do not create work items
• Do not write code
• Web search is mandatory — don't just analyze the codebase
• Keep the doc under 200 lines — concise, not exhaustive
• Unattended: NEVER pause for input; infer and proceed

Capture lessons (exit step)

Before the final verdict line, follow .rdc/guides/lessons-learned-spec.md § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one .rdc/lessons/<YYYY-MM-DD>-preplan-<short-slug>.md per lesson using the schema in that spec. Set scope (simple | architectural) and status (open, or applied if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on develop alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.