dv-plan

name: dv-plan description: Start a new Data Visualization Kit project with structured intake and planning. Use when the user types $dv-plan, starts a new project, has a dataset but unclear scope, needs framework mapping, or needs one canonical project plan file before any downstream $dv-* workflow runs. argument-hint: "[goal / task / brief]" license: MIT metadata: author: data-visualization-kit version: "2.0.0"

DV Plan

Production-ready intake and planning for Data Visualization Kit projects. This is the first project step and it must produce one canonical plan file that downstream skills and workflows can trust.

Workflow Obligation

This skill must follow:

• ./.codex/workflows/primary-workflow.md
• ./.codex/workflows/hook-runtime-contract.md

If this skill and the workflow files disagree, follow the workflow files.

When to Use

• starting a new project from a broad business or portfolio brief
• the user has a dataset but the problem framing is still weak
• the user has context and dataset but goals are vague, missing, or underspecified
• the project needs framework mapping before implementation begins
• downstream $dv-* workflows need one canonical plan file first

Intake Contract

This skill is responsible for collecting and clarifying:

• dataset context
• dataset or source surface
• project goals if the user already has them
• constraints, assumptions, and output expectations when they materially affect the plan

If any of these are vague, ask direct clarification questions until the inputs are trustworthy enough to plan.

Clarification Rules

• clarify the business or portfolio context, not just the table names
• clarify what the dataset actually contains, its likely grain, and any obvious trust gaps
• clarify whether the user wants BI storytelling, operational monitoring, advanced analysis, or a pipeline-heavy portfolio case
• if the user gives weak goals, translate them into sharper analytical questions before planning
• do not pretend missing goals are already clear

Mandatory Decision Gate (REQUIRED — do not skip)

Before producing any plan output, you MUST explicitly confirm all four decisions with the user. Do not auto-select silently. Do not proceed until the user has responded to each question.

Present each decision as a numbered choice with a short description. Wait for the user's selection.

1. Framework

Present both options and ask the user to choose:

Ask: "Which framework fits your project? (1 or 2)"

If the user's brief already contains strong signals (e.g. "ETL pipeline", "forecasting"), suggest a default but still ask to confirm.

2. Goal Tier

Present all three tiers and ask the user to choose:

Suggest concrete goal ideas for each tier based on the user's dataset and context before asking. Ask: "Which goal tier fits your ambition for this project? (1, 2, or 3)"

3. Visualization Tool

Present all five options and ask the user to choose:

Ask: "Which visualization tool should this project use? (1, 2, 3, 4, or 5)"

4. Deploy Target

Present all three options and ask the user to choose:

Ask: "Where will this portfolio project be deployed? (1, 2, or 3)"

If the user selects Netlify or Vercel, suggest Evidence.dev as the visualization tool unless goals are explicitly operational or time-series.

Do not proceed to write the plan until all four decisions are confirmed. Record all four confirmed choices at the top of project-plan.md.

Output Requirement

project-plan.md must record all four confirmed decisions (framework, goal tier, visualization tool, deploy target) at the top, before any phase breakdown.

After the inputs are clear enough, produce one canonical plan file:

• projects/<slug>/docs/project-plan.md

That plan file must be rich enough for downstream $dv-* workflows and skills to continue without guessing.

The generated project workspace must also include project-scoped harness artifacts:

• docs/validation.md for the DV proof matrix
• docs/stories/ for story-sized work packets
• docs/decisions/ for durable project decisions
• docs/assets/harness/traces.jsonl for workflow trace history
• docs/drift-audit.md for stale or contradictory project-state checks

Plan File Must Contain

• user-provided context
• user-provided dataset description
• clarified interpretation of the problem
• clarified or selected goals
• suggested goal ladder with the chosen level called out
• framework recommendation with reasoning
• recommended visualization path
• expected SQL/Python depth
• suggested next workflows after planning
• assumptions, risks, and open questions if any

Handoff Rule

After the plan is locked, always suggest $dv-cook as the primary next command. Do not suggest $dv-data-preparation or $dv-data-visualize as the next step — those are downstream specialist commands invoked from within $dv-cook or by the user for targeted refreshes.

• $dv-cook — primary next command after $dv-plan completes
• $dv-data-preparation — downstream specialist; uses the plan file as its contract, but is not the suggested post-plan command
• $dv-data-visualize — downstream specialist; uses the plan file as its starting contract, but is not the suggested post-plan command

Common Pitfalls To Avoid

1. turning intake into a shallow form-fill exercise
2. accepting vague goals without sharpening them
3. choosing a framework implicitly instead of documenting why
4. producing a plan that downstream skills cannot actually use
5. confusing "dataset description" with "analytical objective"
6. making the plan generic enough to fit anything and guide nothing