Skip to content

vt-c-shape

Pre-plan shaping step that identifies gray areas in a spec and locks implementation decisions before planning begins.

Plugin: core-standards
Category: Other
Command: /vt-c-shape

/vt-c-shape — Pre-Plan Decision Shaping

Workflow Position: /vt-c-activate → /vt-c-shape (optional) → /vt-c-2-plan → /vt-c-3-build → /vt-c-4-review → /vt-c-complete

Inspired by GSD's "discuss" phase — shape implementation decisions before the planner runs.

Purpose

Closes the gap between spec activation and planning. Without shaping, the planner makes reasonable defaults for ambiguous aspects. With shaping, the user locks decisions so the plan matches their actual intent.

When to Use

  • After /vt-c-activate and before /vt-c-2-plan
  • When a spec has ambiguous aspects that could be implemented multiple ways
  • When you have a strong opinion about HOW something should be built (not just WHAT)

This step is optional. /vt-c-2-plan works without it. Use it when you want more control over planning decisions.

Invocation

/vt-c-shape                       # Shape the active spec (derived from branch)

Execution Steps

Step 1: Load Active Spec

  1. Derive active spec from branch:
  2. Check .active-spec file first
  3. Then parse branch name (feature/spec-NNN-* → SPEC-NNN)
  4. Look up specs_dir in .design-state.yaml
  5. Load specs/[N]-feature/spec.md
  6. If no active spec found: 
    No active spec found. Run /vt-c-activate first.

Step 2: Analyze for Gray Areas

Read the spec and identify ambiguous aspects based on the spec's domain. Generate 3-7 targeted questions that would constrain the planner.

Domain-specific question areas:

UI / Frontend specs: - Layout density and spacing approach - Interaction patterns (modals vs inline, drag-drop vs buttons) - Responsive behavior (mobile-first? breakpoints?) - Empty states and loading states - Accessibility requirements

API / Backend specs: - Response format (REST conventions, pagination, error shapes) - Error handling strategy (fail-fast vs graceful degradation) - Authentication and authorization approach - Rate limiting and caching strategy - Versioning approach

Data specs: - Validation rules and strictness - Migration strategy (zero-downtime? backfill?) - Edge cases (empty values, unicode, large datasets) - Consistency requirements (eventual vs strong)

Workflow / Process specs: - Trigger conditions and timing - Failure modes and recovery - State transitions and valid sequences - Notification and feedback mechanisms - Integration points with other skills/agents

Step 2.5: Strategic Review

Before asking shaping questions, dispatch the strategic-mentor agent (read-only, via Agent tool) to assess the spec's strategic viability:

  1. Dispatch with:
  2. specs/[N]-feature/spec.md (required)
  3. .specify/memory/constitution.md (if exists)
  4. The agent returns a verdict (VIABLE / NEEDS REVISION / FLAWED) with analysis of assumptions, failure modes, and risks
  5. Display the verdict and key findings to the user
  6. Use the strategic findings to inform which gray areas matter most in Step 3 — prioritize questions that address the mentor's identified assumptions and failure modes

If the verdict is NEEDS REVISION, note the specific weaknesses before proceeding: 

Strategic Review: NEEDS REVISION
[Summary of weaknesses]

Consider addressing these points during shaping — the questions below
will prioritize the mentor's identified concerns.

If the verdict is FLAWED, warn the user before proceeding to questions: 

Strategic Review: FLAWED
[Summary of critical issues]

The strategic-mentor flagged fundamental issues with this spec.
Consider revising the spec before shaping implementation decisions.

Step 3: Ask Questions

Use AskUserQuestion to ask 3-7 targeted questions. Each question should: - Reference the specific ambiguous aspect of the spec - Provide 2-4 concrete options (not open-ended) - Include a recommended option when one is clearly better

Example for a workflow spec: 

Question: "How should wave computation handle specs with
           partially-met dependencies?"
Options:
  - Strict: only include specs where ALL deps are completed
  - Lenient: include specs where deps are in_progress (Recommended)
  - Configurable: let the user choose per invocation

Step 4: Save Decisions

Write answers to specs/[N]-feature/decisions.md:

# Implementation Decisions for SPEC-{id}: {title}

Shaped: {date}

## Decision 1: {topic}
**Question**: {what was asked}
**Answer**: {user's chosen option}
**Implication**: {how this constrains the plan — what the planner should do differently}

## Decision 2: {topic}
**Question**: {what was asked}
**Answer**: {user's chosen option}
**Implication**: {how this constrains the plan}

...

Architecture decisions format: When a gray area involves a technology choice, integration pattern, or scaling decision, use this structured format instead of the default:

## Decision N: {topic}
**Context**: {business constraints understood}
**Options**:
  - A. {option} — Pros: {list} / Cons: {list} / Risk: {assessment}
  - B. {option} — Pros: {list} / Cons: {list} / Risk: {assessment}
  - C. {option} — Pros: {list} / Cons: {list} / Risk: {assessment}
**Recommendation**: {chosen option and why}
**What Breaks First**: {scaling bottleneck or failure point under load}

Use the default Question/Answer/Implication format for non-architectural decisions (naming, scope, feature boundaries, UX choices).

Step 4.5: Optional Strategic Review

After saving decisions, offer the user a strategic review of the spec:

Use AskUserQuestion: - Run strategic review (Recommended) — dispatches strategic-mentor agent with spec.md as input to challenge assumptions and identify failure modes before planning begins - Skip — proceed directly to summary

If accepted: dispatch strategic-mentor agent via Agent tool with the active specs/[N]-feature/spec.md as input. Note: this reviews the spec, not a plan — the plan doesn't exist yet at this stage. The strategic-mentor will produce a verdict (VIABLE / NEEDS REVISION / FLAWED) with structured analysis.

Display the strategic-mentor verdict to the user before proceeding to Step 5.

Step 5: Display Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Shaping Complete: SPEC-{id} — {title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{N} decisions locked in specs/[N]-feature/decisions.md

Key decisions:
• {decision 1 summary}
• {decision 2 summary}
• ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT STEP: /vt-c-2-plan (will consume your decisions automatically)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━