vs-core-rfc

name

vs-core-rfc

description

RFC and feature design pipeline from concept to implementation spec. Use this skill when the user wants to design a new feature end-to-end, write an RFC, create a technical specification, or go from idea to implementation plan. Also use when the user says "RFC", "design a feature", "spec this out", "technical design", "feature design", or describes a substantial new capability that needs design before implementation.

Artifact Profile

Read ../vs-core-_shared/prompts/artifact-persistence.md for the full protocol.

• stage_name: rfc
• artifact_filename: rfc.md
• write_cardinality: single
• upstream_reads: grill, research
• body_format:

  # Spec: [Feature Name]
  **Status**: Proposed
  ## Problem Statement
  ## Design Decisions
  ## Assumptions
  ## Vertical Slices
  ## Out of Scope
  ## Open Questions
  ## Evolution Log
  *Maintained in the implementation artifact.*
  

RFC / Feature Design Pipeline

You are an RFC coordinator. You guide a feature from rough idea to a living implementation spec with vertical slices ready for /vs-core-implement. The spec is not a waterfall artifact -- it is a living document that evolves during implementation and is validated only when implementation confirms its assumptions.

How to Dispatch Agents

This skill invokes /vs-core-grill (Phase 1) and /vs-core-research (Phase 2) via the Skill tool -- those run their own logic, not as sub-agents. Only Phase 3 (designers) and Phase 4 (reviewers + revision-designer) use sub-agent dispatch.

When this skill says "dispatch" an agent, you MUST use the --tmp flow to keep your own context clean. The spec-methodology reference is 14KB; pulling it into your context via Read() or captured stdout would burn tokens on content only the sub-agent needs.

The flow:

1. Build the prompt file. From this skill's directory:

   bash build-prompt.sh --tmp <role>
   

   <role> is one of: designer, adversarial-design, feasibility, revision-designer. The script writes all mandated references (trust boundary, output format, rationalization rejection, self-critique protocol, spec methodology, and the role prompt) into a new temp file and prints only the path to stdout. Do NOT run the script without --tmp, and do NOT Read() any reference files yourself (spec-methodology.md, etc.) -- the script already inlined them into the temp file.

2. Capture the printed path (e.g. /tmp/vs-rfc.IPc3vr6b.md).

3. Dispatch the Agent with a short prompt that points at the temp file and adds task-specific context:

   Your complete instructions are in <TMP_FILE>. Read that file in full before
   doing anything else.
   
   Task: [requirements from grill, research findings (if run), this agent's
          specific constraint or review focus. For revision-designer: merged
          Phase 4 findings + most recent Reflection.]
   

   Use the model specified for the role.

4. Launch independent agents in a single message for parallel execution.

Artifact Flow

1. Before Phase 1 begins: Run ARTIFACT_DISCOVERY (see artifact-persistence.md). Establish the feature slug silently if unambiguous.
2. Upstream reads: Run UPSTREAM_CONSUMPTION for grill and research.
   • If grill.md exists, read it and use it as Phase 1 context -- you may skip or shorten the live /vs-core-grill invocation at your judgment.
   • If research.md exists, read it and use it as Phase 2 context -- you may skip or shorten the live /vs-core-research invocation at your judgment.
   • If either file is missing, warn: "Expected upstream artifact {stage}.md not found. Proceed without it?" Wait for confirmation before continuing.
   • Additionally: if .spec/{slug}/mission.md exists, read it. If MISSION exists but rfc.md doesn't, this is a redesign loop — surface prior decisions from the Decision Log. If rfc.md is rewritten in Phase 5, append a [kind=spec-revised] Decision Log entry to MISSION.
3. Nested invocation rule: When /vs-core-rfc invokes /vs-core-grill (Phase 1) or /vs-core-research (Phase 2) internally via the Skill tool, those sub-skills run their logic normally but do NOT execute their own artifact persistence protocol. They do not write grill.md or research.md. Their output feeds /vs-core-rfc directly, not the filesystem.
4. After Phase 5 produces the living spec: Run WRITE_ARTIFACT -- write rfc.md to .spec/{slug}/ with the frontmatter schema and the spec document as the body.

Phase 1: Scope

Use the Skill tool to invoke /vs-core-grill. Do NOT copy-paste the grill logic -- invoke the actual skill.

The grill must produce:

• A decisions list (concrete choices made)
• Open questions that need research
• Whether Phase 2 (Research) is needed or can be skipped

If the grill determines the domain is well-understood and no unknowns exist, skip Phase 2.

Phase 2: Research (when needed)

Use the Skill tool to invoke /vs-core-research with the open questions from Phase 1. Do NOT copy-paste research logic -- invoke the actual skill.

The research must answer the open questions with evidence. Its output feeds directly into Phase 3.

Phase 3: Design -- "Design It Twice"

Dispatch 3+ parallel design agents (model: strong), each with a radically different constraint, using:

bash build-prompt.sh --tmp designer

Give each designer (via the TASK-SPECIFIC CONTEXT marker):

• The same requirements (from Phase 1 grill output)
• The same research findings (from Phase 2, if run)
• A different constraint that forces a fundamentally different approach

Example constraints (adapt to the problem):

• "Minimize the API surface -- fewest possible methods/types"
• "Maximize flexibility -- support use cases we haven't thought of yet"
• "Optimize for the common case -- make the 90% path trivially simple"
• "Use [specific paradigm]: actor model, ECS, event-driven, functional core, etc."

Present all designs side by side. Compare on:

• Interface simplicity (fewer concepts = better)
• What each design hides from callers
• How each would evolve as requirements change
• What each design bets on (direction of future change)
• Assumption risk (which design has the most dangerous assumptions?)

Recommend one. Wait for user approval before proceeding.

Phase 4: Adversarial Review

Dispatch 2 parallel reviewers on the chosen design:

Adversarial Design Reviewer (model: strongest)

bash build-prompt.sh --tmp adversarial-design

Feasibility Reviewer (model: strong)

bash build-prompt.sh --tmp feasibility

Critical Merge (after both reviewers return)

Read and follow ../vs-core-_shared/prompts/critical-merge.md to reconcile the two reports:

• Resolve contradictions between the adversarial and feasibility reviewers
• Pay special attention to assumption verification: if the feasibility reviewer CONTRADICTED a numbered assumption, that is automatically Critical severity
• Assign unified severity ratings across all findings
• Produce a single merged findings document

The merged findings (not the raw reviewer outputs) drive the revision decision.

If the merged findings contain Critical issues, run the revision loop (max 3 cycles):

Step 1: Reflect (coordinator, not a separate agent)

Write a structured reflection diagnosing what design assumption produced the Critical issues. This is a verbal gradient in the Reflexion style -- it tells the revision agent WHY the design was flawed.

Format:

### Reflection

**Flawed assumption**: [The specific assumption -- reference by number if it's a listed assumption]
**Evidence**: [Which reviewers flagged it and what their findings show]
**What must change**: [The conceptual shift needed -- not a specific fix, but a different way of thinking about this part]

Only the most recent reflection is passed forward; do not accumulate reflections across cycles.

Step 2: Revise

Dispatch a revision-designer agent (model: strong) using:

bash build-prompt.sh --tmp revision-designer

Append to the TASK-SPECIFIC CONTEXT marker:

• The current design
• The merged findings document
• The reflection from Step 1

Step 3: Re-review

Dispatch both reviewers on the revised design, then apply critical-merge again.

Step 4: Loop or exit

• No Critical issues -> proceed to Phase 5
• Critical issues remain, cycle < 3 -> return to Step 1
• 3 cycles exhausted -> escalate to the user with the final merged findings, the most recent reflection, and a recommendation to reconsider the approach

Phase 5: Spec Generation

Generate the living spec document -- the contract between /vs-core-rfc and /vs-core-implement.

Read prompts/spec-template.md for the exact template and principles. Follow it precisely.

Key requirements:

• Every assumption numbered and traced to design decisions and slices
• Every slice has acceptance criteria in durable language (behaviors, not file paths)
• Every slice declares which assumptions it validates
• Evolution Log starts empty -- /vs-core-implement populates it
• Status starts as "Proposed"

Output is ready to feed directly into /vs-core-implement.

Tell the user: "The spec is ready. Invoke /vs-core-implement when you want to start implementation. During implementation, if any numbered assumption proves wrong, /vs-core-implement will pause and present options."