Overview

Create dt-rpi-handoff-contract.instructions.md, the architectural specification defining how DT coaching sessions produce artifacts that feed into the RPI pipeline. This contract specifies:

• What the coach produces at each DT space boundary (exit-point artifacts)
• What each RPI agent expects as input (input contracts)
• How graduation awareness triggers the handoff decision
• How subagent dispatch supports readiness assessment before handoff

This is a cross-cutting architectural concern moved from Phase 5 to Phase 3 because it informs all three space-specific handoff prompts (#590, #603, #611) and the DT-aware RPI context files (#593-#595).

Dependency note: This issue depends on the DT coach agent definition (#579 from Phase 2), which establishes the coaching identity, state management, and graduation awareness behavior referenced in this contract.

Directory note: The .copilot-tracking/dt/ directory is a per-project workspace created when a user initializes a DT coaching session. The coach agent (#579) defines the initialization workflow that creates this directory structure.

Target File

.github/instructions/dt-rpi-handoff-contract.instructions.md

Frontmatter

---
description: 'DT→RPI handoff contract — exit-point schemas, RPI input contracts, graduation awareness, and subagent dispatch'
applyTo: '**/.copilot-tracking/dt/**'
---

Required Content

Tiered Handoff Schema

Three exit points, one per DT space:

Phase scope: This issue defines the contract for all three exit points. The Problem Space exit prompt is #590 (this phase). Solution Space exit (#603) and Implementation Space exit (#611) prompts are planned for Phase 5.

Exit-Point Artifact Schema

Each exit-point handoff prompt produces a structured artifact:

handoff:
  source: "dt-coach"
  exit_point: "problem-space"  # problem-space | solution-space | implementation-space
  project: "{{project-slug}}"
  methods_completed: [1, 2, 3]

  ## Problem Space Exit artifacts
  problem_statement:
    pov: "[User] needs [need] because [insight]"
    validated_assumptions: []
    open_assumptions: []
  stakeholder_map:
    groups: []
    key_relationships: []
    missing_voices: []
  research_summary:
    themes: []
    key_insights: []
    evidence_strength: "strong | moderate | emerging"
  gap_analysis:
    validated: []
    unknown: []
    recommended_research: []

  ## Solution Space Exit artifacts (extend for #603)
  concept_evaluation:
    concepts_tested: []
    selection_criteria: []
    stakeholder_feedback: []
  prototype_results:
    fidelity_level: "lo-fi | medium | hi-fi"
    key_findings: []
    iteration_history: []
  solution_specification:
    selected_concept: ""
    design_rationale: ""
    constraints_addressed: []

  ## Implementation Space Exit artifacts (extend for #611)
  implementation_spec:
    components: []
    acceptance_criteria: []
    stakeholder_sign_off: []
  test_results:
    test_approach: ""
    outcomes: []
    iteration_count: 0
  deployment_plan:
    rollout_strategy: ""
    monitoring_criteria: []
    feedback_loops: []

  ## Metadata
  dt_space: "problem"  # problem | solution | implementation
  hint_calibration_level: 2
  session_count: 3
  coaching_notes: |
    Free-text context from the coach about what was covered,
    what the user cares about most, and recommended next steps.

RPI Input Contracts

What each RPI agent expects from a DT handoff:

Graduation Awareness Behavior

The coach triggers graduation awareness when:

1. The user completes the final method of a DT space (Method 3, 6, or 9)
2. The user explicitly asks to "hand off" or "start building" or equivalent
3. The user's work quality signals readiness (completion signals from method sequencing)

Graduation awareness flow:

1. Coach summarizes the current space's outputs
2. Coach assesses artifact completeness against the exit-point schema
3. Coach presents three choices: continue to next DT space, hand off to RPI, or revisit earlier methods
4. If user chooses handoff, coach triggers readiness assessment via subagent (feat(instructions): Subagent handoff workflow specification #592)
5. If readiness is confirmed, coach invokes the appropriate space exit handoff prompt

Handoff Quality Markers

Each artifact in the exit schema has quality markers:

• Validated: Evidence-backed, reviewed by stakeholders or through research
• Assumed: Coach and user believe this is true but haven't validated it
• Unknown: Identified gap requiring further investigation
• Conflicting: Multiple stakeholders or data sources disagree

The coach explicitly marks these before handoff so RPI agents know what to trust and what to investigate.

Token Budget

Target: ~1,500-2,000 tokens (ambient tier, always loaded in DT context)

Source Material

Attach these files as context for the task-researcher phase:

• RPI agent definitions: .github/agents/task-researcher.agent.md, task-planner.agent.md, task-implementor.agent.md, task-reviewer.agent.md — extract input contracts and handoff patterns
• Cumulative research: Design Thinking cumulative research — Part 6 (technical design) for DT→RPI handoff architecture and Part 10 (implementation roadmap) for phased delivery strategy
• DT4HVE coaching hats: design-thinking-for-hve-capabilities/.github/chatmodes/hats/ — method-specific coaching patterns that produce exit artifacts

RPI Pipeline Workflow

1. task-researcher: Gather DT4HVE handoff patterns, RPI agent input expectations (from existing agent definitions), and the DT-RPI integration design from cumulative research Parts 6 and 10.
2. task-planner: Plan the contract — tiered schema, artifact definitions per exit point, RPI input contracts, graduation awareness, quality markers.
3. task-implementor: Author following prompt-builder standards. The contract is a specification, precise enough for handoff prompts to implement.
4. task-reviewer: Validate schema completeness, RPI contract accuracy against actual agent definitions, graduation awareness flow, prompt-builder compliance.

Starter Prompts

Research: /task-research — "Gather DT4HVE handoff patterns, RPI agent input expectations from existing agent definitions, and the DT-RPI integration design from cumulative research Parts 6 and 10. Attach all 4 RPI agent files and cumulative research as context."

Plan: /task-plan — "Plan dt-rpi-handoff-contract.instructions.md — tiered exit schema (3 exit points), artifact definitions per space, RPI input contracts per agent, graduation awareness flow, quality markers."

Implement: /task-implement — "Author dt-rpi-handoff-contract.instructions.md following prompt-builder standards with applyTo glob for .copilot-tracking/dt/**, 1500-2000 token budget."

Review: /task-review — "Validate dt-rpi-handoff-contract.instructions.md against prompt-builder standards, RPI contract accuracy against actual agent definitions, and graduation awareness flow."

Success Criteria

• Contract file created at .github/instructions/dt-rpi-handoff-contract.instructions.md
• Frontmatter has applyTo: '**/.copilot-tracking/dt/**' glob (ambient loading)
• Three exit points defined with artifact schemas (Problem, Solution, Implementation)
• RPI input contracts specify required and optional inputs per agent
• Graduation awareness behavior covers completion triggers, assessment flow, three-choice presentation
• Handoff quality markers (validated, assumed, unknown, conflicting) defined
• Contract is precise enough for handoff prompt implementation
• Token count within ~1,500-2,000 target
• Passes task-reviewer validation against prompt-builder standards
• Artifact registered in collections/design-thinking.collection.yml with path and kind fields
• Artifact registered in collections/hve-core-all.collection.yml with path and kind fields
• npm run plugin:generate run after updating collection manifests