Overview

Create the coaching state protocol instruction file that defines how coaching state is created, updated, recovered, and validated. This is the contract between the dt-coach agent, the start-project prompt, and the resume-coaching prompt for session persistence.

Target File

.github/instructions/dt-coaching-state.instructions.md

Frontmatter

---
description: 'Design Thinking coaching state protocol — YAML schema, lifecycle management, and session recovery'
applyTo: '**/.copilot-tracking/dt/**/coaching-state.md'
---

Required Content

State Schema

project: "{{project-slug}}"
current_method: 1
current_phase: "planning"  # planning | execution | documentation
dt_space: "problem"  # problem | solution | implementation
methods_completed: []
methods_in_progress: []
hint_calibration:
  level: 1  # 1-4
  pattern_notes: ""  # Free-text notes on user's help-seeking patterns
user_preferences:
  detail_level: "moderate"  # brief | moderate | detailed
  coaching_style: "collaborative"  # collaborative | directive-light
industry_context: ""  # Loaded industry template name, if any
session_recovery_instructions: |
  Free-text recovery context written by the coach at session end.
  Includes: what was discussed, where the user was heading, any
  open questions or decisions pending.
last_updated: "2026-01-01T00:00:00Z"

State Lifecycle

Directory Structure

.copilot-tracking/dt/{project-slug}/
├── coaching-state.md           # State file (YAML content in markdown)
├── industry-context.md         # Industry template (if loaded)
├── method-01-scope/            # Method 1 artifacts
│   ├── stakeholder-map.md
│   ├── scope-boundaries.md
│   └── assumptions-log.md
├── method-02-research/         # Method 2 artifacts
│   ├── research-plan.md
│   └── raw-findings.md
└── ...                         # Additional method directories

Validation Rules

• current_method must be 1-9
• current_phase must be one of: planning, execution, documentation
• dt_space must be one of: problem, solution, implementation
• dt_space must be consistent with current_method: 1-3 = problem, 4-6 = solution, 7-9 = implementation
• methods_completed must not contain current_method
• hint_calibration.level must be 1-4
• last_updated must be valid ISO 8601

Recovery Robustness

When state is missing or corrupted:

• Missing fields: Use defaults from the creation schema
• Invalid values: Log warning, use nearest valid value
• Missing state file: Prompt user to start a new project
• Conflicting values (e.g., method 5 but space "problem"): Trust current_method, derive dt_space

Token Budget

Target: ~800-1,000 tokens (auto-loaded when coaching-state.md is open)

How to Build This File

This is an .instructions.md file — use the prompt-builder agent (not task-implementor) for the authoring phase. The prompt-builder includes built-in Prompt Quality Criteria validation and sandbox testing specific to AI artifacts (.instructions.md, .prompt.md, .agent.md, SKILL.md).

Workflow: /task-research → /task-plan → /prompt-build → /task-review

Between each phase, use /clear to reset context, then attach the output artifact from the previous phase as input for the next.

Phase 1: Research

Gather source material for the Coaching State instructions file.

Source Material: The upstream state management patterns — YAML schema
conventions, session persistence, lifecycle events, and recovery behavior — are
defined in the DT4HVE repository:

design-thinking-for-hve-capabilities/.github/chatmodes/design-thinking.chatmode.md

The chatmode defines how coaching state is read, written, and recovered across
sessions. State references throughout the chatmode reveal the YAML schema
fields, lifecycle transitions, and validation expectations. If you don't have
the DT4HVE repository cloned, ask a maintainer for access.

Steps:

1. Type /clear to start a fresh conversation.
2. Attach the DT4HVE chatmode file listed above as context.
3. Copy the prompt below into chat and send.

/task-research topic="DT coaching state schema for hve-core"

Research the Design Thinking coaching state management patterns for an
.instructions.md file targeting
`.github/instructions/dt-coaching-state.instructions.md`.

Use the attached DT4HVE Design Thinking Coach chatmode as the primary source.
Extract and analyze:
- YAML schema for coaching-state.md: all fields, types, defaults, constraints
- State lifecycle events: creation, updates during coaching, session end
- Directory structure: `.copilot-tracking/dt/{project-name}/coaching-state.md`
- Validation rules: required fields, valid value ranges, schema integrity
- Recovery behavior: how agents handle missing, corrupted, or partially written
  state files
- State transitions: how field values change as coaching progresses through
  methods and spaces

Focus areas:
- Complete YAML schema with every field the coaching agent reads or writes
- Which fields are set at initialization vs. updated during coaching
- How state validation prevents silent corruption
- How recovery behavior restores a usable state from edge cases
- How the schema supports the 9-method, 3-space coaching model

The research output will feed `/task-plan` and then `/prompt-build` to author
the instructions file.

Output: DT coaching state research

Phase 2: Plan

Plan the file structure and schema organization using the research output.

Steps:

1. Type /clear to reset the conversation.
2. Attach the research document from Phase 1 (from the research phase above).
3. Copy the prompt below into chat and send.

/task-plan

Plan the implementation of
`.github/instructions/dt-coaching-state.instructions.md` — an auto-loaded
instruction file that defines the YAML schema and lifecycle for coaching state.

Use the attached research document as the primary input.

The plan should cover:
- Frontmatter structure
  (`description`, `applyTo: '**/.copilot-tracking/dt/**/coaching-state.md'`)
- YAML schema definition with field types, defaults, and constraints
- State lifecycle: creation defaults, coaching updates, session end
- Directory structure convention
- Validation rules for schema integrity
- Recovery behavior for missing, corrupted, or partial state files
- Token budget target: ~800-1,000 tokens (auto-loaded when coaching-state.md
  is open)

The implementation phase will use `/prompt-build` (not task-implementor) since
this is an AI artifact file.

Output: .copilot-tracking/plans/{date}-dt-coaching-state-plan.md

Phase 3: Build

Author the instruction file using the prompt-builder agent. Prompt-builder handles authoring standards (frontmatter, writing style, progressive disclosure) automatically through its built-in Prompt Quality Criteria validation.

Steps:

1. Type /clear to reset the conversation.
2. Attach the plan document from Phase 2 (find it in .copilot-tracking/plans/).
3. Copy the prompt below into chat and send.

/prompt-build file=.github/instructions/dt-coaching-state.instructions.md

Build the DT Coaching State instructions file following the attached
implementation plan.

Requirements:
- Auto-loaded instruction file on `**/.copilot-tracking/dt/**/coaching-state.md`
  paths
- YAML schema with all fields, types, defaults, and constraints
- State lifecycle: creation defaults, coaching session updates, session end
- Directory structure: `.copilot-tracking/dt/{project-name}/coaching-state.md`
- Validation rules that prevent silent corruption
- Recovery behavior for missing, corrupted, or partial state files
- Schema must be clear enough that agents can read/write state without ambiguity
- Token budget: ~800-1,000 tokens (this file auto-loads, so brevity matters)
- Nativize DT4HVE content for HVE Core context — avoid source-specific
  references

Output: .github/instructions/dt-coaching-state.instructions.md

Phase 4: Review

Validate the instruction file against the plan and prompt-builder standards.

Steps:

1. Type /clear to reset the conversation.
2. Attach the plan document from Phase 2 and the new instruction file from Phase 3.
3. Copy the prompt below into chat and send.

/task-review

Review the implementation of
`.github/instructions/dt-coaching-state.instructions.md` against the
attached plan.

Validate:
- Prompt Quality Criteria from `.github/instructions/prompt-builder.instructions.md`
- YAML schema covers all fields with types, defaults, and constraints
- State lifecycle events are defined (creation, update, session end)
- Directory structure follows `.copilot-tracking/dt/{project-name}/` convention
- Validation rules prevent silent state corruption
- Recovery behavior handles missing, corrupted, and partial state files
- Schema is unambiguous for agent read/write operations
- Token count is within ~800-1,000 target (auto-loaded budget)
- Frontmatter has correct
  `applyTo: '**/.copilot-tracking/dt/**/coaching-state.md'` glob
- No temporal markers, task IDs, or DT4HVE-specific references remain
- Writing style follows prompt-builder standards: guidance over commands,
  `*` bullets, `**bold**` for key concepts

Output: .copilot-tracking/reviews/{date}-dt-coaching-state-review.md

After Review

The reviewer reports one of three outcomes:

• Pass — The instruction file meets all criteria. Open a PR with the new file.
• Iterate — The reviewer identified specific issues. Return to Phase 3: /clear, attach the review document, then re-run /prompt-build with the fixes noted.
• Escalate — Fundamental gaps need more research. Return to Phase 1 to investigate the identified areas.

Success Criteria

• Instruction file created at .github/instructions/dt-coaching-state.instructions.md
• Frontmatter applyTo targets coaching-state.md files
• YAML schema defined with all required fields
• State lifecycle covers creation, transitions, escalation, session end/resume
• Directory structure documented for coaching artifacts
• Validation rules prevent inconsistent state
• Recovery behavior handles missing/corrupted state gracefully
• Token count within ~800-1,000 target
• Passes task-reviewer validation against prompt-builder standards