Skip to content

Commit 5a5be4e

Browse files
chaosdinosaurCopilotagreaves-ms
authored
feat(instructions): add DT coaching state protocol for session persistence (#654)
# Pull Request ## Description > **Note:** This PR depends on #642, #645, #650, #651, #652, #653 (Phase 1 foundation) being merged first. Add `dt-coaching-state.instructions.md`, which defines the YAML-based coaching state schema for Design Thinking session persistence. The state file tracks method progress across sessions and enables the coach to resume seamlessly by reading project metadata, the current method/space/phase, transition history, session logs, and produced artifacts. ## Related Issue(s) Closes #582 ## Type of Change Select all that apply: **Code & Documentation:** - [ ] Bug fix (non-breaking change fixing an issue) - [x] New feature (non-breaking change adding functionality) - [ ] Breaking change (fix or feature causing existing functionality to change) - [ ] Documentation update **Infrastructure & Configuration:** - [ ] GitHub Actions workflow - [ ] Linting configuration (markdown, PowerShell, etc.) - [ ] Security configuration - [ ] DevContainer configuration - [ ] Dependency update **AI Artifacts:** - [x] Reviewed contribution with `prompt-builder` agent and addressed all feedback - [x] Copilot instructions (`.github/instructions/*.instructions.md`) - [ ] Copilot prompt (`.github/prompts/*.prompt.md`) - [ ] Copilot agent (`.github/agents/*.agent.md`) - [ ] Copilot skill (`.github/skills/*/SKILL.md`) **Other:** - [ ] Script/automation (`.ps1`, `.sh`, `.py`) - [ ] Other (please describe): ## Sample Prompts (for AI Artifact Contributions) **User Request:** > Resume my design thinking coaching session for the factory floor maintenance project. **Execution Flow:** 1. Coach reads `.copilot-tracking/dt/factory-floor-maintenance/coaching-state.md`. 2. Parses YAML schema: validates `project`, `current`, `methods_completed`, and `transition_log` fields. 3. Restores context from `current.method` (e.g., 3), `current.space` (`problem`), and `current.phase` (e.g., `theme clustering`). 4. Reviews latest `session_log` and `transition_log` entries to summarize where the team left off. 5. Scans `artifacts` list for available project outputs to reference. 6. Announces resumed state to the user with current method, phase, and a brief summary of previous work. **Output Artifacts:** ```yaml # .copilot-tracking/dt/factory-floor-maintenance/coaching-state.md project: name: "Factory Floor Maintenance" slug: "factory-floor-maintenance" created: "2026-02-18" initial_request: "Reduce unplanned downtime on the factory floor" initial_classification: "fluid" current: method: 3 space: "problem" phase: "theme clustering" --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Allen Greaves <[email protected]>
1 parent e465b2f commit 5a5be4e

8 files changed

Lines changed: 158 additions & 0 deletions

File tree

‎.github/instructions/design-thinking/dt-coaching-state.instructions.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
description: 'Coaching state schema for Design Thinking session persistence, method progress tracking, and session recovery'
3+
applyTo: '**/.copilot-tracking/dt/**/coaching-state.md'
4+
---
5+
6+
# DT Coaching State Protocol
7+
8+
This instruction defines the coaching state schema, file conventions, and session management protocol for Design Thinking projects. The state file tracks method progress across sessions and enables the coach to resume seamlessly.
9+
10+
## State File Location
11+
12+
Store the coaching state file at `.copilot-tracking/dt/{project-slug}/coaching-state.md`.
13+
14+
* `{project-slug}` is a kebab-case identifier derived from the project name (e.g., `factory-floor-maintenance`, `patient-handoff-optimization`).
15+
* Create the directory when initializing a new coaching project.
16+
* One state file per project. Multiple concurrent projects each get their own directory.
17+
18+
## State File Schema
19+
20+
```yaml
21+
# .copilot-tracking/dt/{project-slug}/coaching-state.md
22+
project:
23+
name: "Human-readable project name"
24+
slug: "kebab-case-identifier"
25+
created: "YYYY-MM-DD"
26+
initial_request: "Original customer request verbatim"
27+
initial_classification: "frozen | fluid"
28+
29+
current:
30+
method: 1 # integer 1-9
31+
space: "problem" # problem | solution | implementation
32+
phase: "" # free-text label for step within current method
33+
34+
methods_completed: [] # list of integers, e.g. [1, 2, 3]
35+
36+
transition_log:
37+
- from_method: null
38+
to_method: 1
39+
rationale: "Project initialized"
40+
date: "YYYY-MM-DD"
41+
42+
session_log:
43+
- date: "YYYY-MM-DD"
44+
method: 1
45+
summary: "Brief description of session work"
46+
47+
artifacts: []
48+
# - path: ".copilot-tracking/dt/{project-slug}/stakeholder-map.md"
49+
# method: 1
50+
# type: "stakeholder-map"
51+
```
52+
53+
### Field Definitions
54+
55+
#### Project Block
56+
57+
* `name`: display name for the project, set during initialization.
58+
* `slug`: kebab-case identifier matching the directory name.
59+
* `created`: ISO 8601 date when the project was initialized.
60+
* `initial_request`: verbatim customer request captured at project start. Preserved as-is for comparison against discovered problem space.
61+
* `initial_classification`: frozen or fluid classification from Method 1 assessment.
62+
63+
#### Current Block
64+
65+
* `method`: integer 1-9 indicating the active method.
66+
* `space`: derived from method number. Methods 1-3 map to `problem`, 4-6 to `solution`, 7-9 to `implementation`.
67+
* `phase`: free-text label describing the current step within the method (e.g., "stakeholder mapping", "interview planning", "theme clustering", "prototype testing").
68+
69+
#### Methods Completed
70+
71+
List of method numbers the team has finished. A method is complete when the coach and team agree its outputs are sufficient to proceed. Once added, methods remain in this list even if they are revisited later.
72+
73+
#### Transition Log
74+
75+
Chronological record of method transitions. Each entry captures:
76+
77+
* `from_method`: source method number (null for initial entry).
78+
* `to_method`: target method number.
79+
* `rationale`: brief explanation of why the transition occurred.
80+
* `date`: ISO 8601 date.
81+
82+
Non-linear iteration produces backward transitions (e.g., from Method 6 back to Method 2). These are normal and recorded with rationale.
83+
84+
#### Session Log
85+
86+
Chronological record of coaching sessions. Each entry captures:
87+
88+
* `date`: ISO 8601 date.
89+
* `method`: active method during the session.
90+
* `summary`: brief description of work accomplished.
91+
92+
#### Artifacts
93+
94+
List of artifacts produced during coaching. Each entry captures:
95+
96+
* `path`: relative path to the artifact from workspace root.
97+
* `method`: method number that produced the artifact.
98+
* `type`: artifact type descriptor (e.g., "stakeholder-map", "interview-notes", "synthesis-themes", "concept-sketch", "prototype-feedback").
99+
100+
## State Management Rules
101+
102+
### Initialization
103+
104+
Create the state file when starting a new coaching project via the `dt-start-project` prompt. Set `current.method` to 1, `current.space` to `problem`, and record the initial transition log entry.
105+
106+
### Updates
107+
108+
Update the state file at these events:
109+
110+
* Method transition (forward, backward, or lateral): update `current` block and append to `transition_log`. When the transition reflects that the current method is complete (the coach and team agree its outputs are sufficient to proceed), add the departing method to `methods_completed` if not already present.
111+
* Session start: append to `session_log` with current date and active method.
112+
* Artifact creation: append to `artifacts` list.
113+
* Phase change within a method: update `current.phase`.
114+
115+
### Space Derivation
116+
117+
Always derive `current.space` from `current.method`:
118+
119+
* Methods 1-3: `problem`
120+
* Methods 4-6: `solution`
121+
* Methods 7-9: `implementation`
122+
123+
Do not set space independently of method.
124+
125+
## Session Recovery Protocol
126+
127+
When resuming a coaching session:
128+
129+
1. Read the state file at `.copilot-tracking/dt/{project-slug}/coaching-state.md`.
130+
2. Verify the file parses as valid YAML and contains required fields (`project`, `current`, `methods_completed`, `transition_log`).
131+
3. Restore coaching context from `current.method`, `current.space`, and `current.phase`.
132+
4. Review the most recent `transition_log` and `session_log` entries to understand where the team left off.
133+
5. Check `methods_completed` to understand overall progress.
134+
6. Scan the `artifacts` list for available project artifacts to reference.
135+
7. Announce the resumed state to the user: current method, current phase, and a brief summary of previous work.
136+
137+
If the state file is missing or corrupted, inform the user and offer to reinitialize from scratch or reconstruct state from existing artifacts in the project directory.
138+
139+
## Project Directory Contents
140+
141+
The `.copilot-tracking/dt/{project-slug}/` directory holds all project-specific artifacts alongside the state file:
142+
143+
* `coaching-state.md`: coaching state (this schema).
144+
* Method outputs: stakeholder maps, interview notes, synthesis documents, concept descriptions, prototype feedback, testing results.
145+
* Naming convention: use descriptive kebab-case filenames prefixed with the method number (e.g., `method-01-stakeholder-map.md`, `method-03-synthesis-themes.md`).
146+
147+
## Integration with Method Sequencing
148+
149+
The coaching state schema aligns with the method routing assessment flow used during method sequencing. The `current.method` field drives which method-tier instructions load via `applyTo` pattern matching. The `transition_log` provides the history that the method sequencing transition protocol references.

‎collections/design-thinking.collection.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ Coaching identity, quality constraints, and methodology instructions for AI-enha
33
This collection includes instructions for:
44

55
- **DT Coaching Identity** — Defines the coach's interaction philosophy (Think, Speak, Empower), progressive hint engine, psychological safety patterns, and hat-switching framework for consistent behavior across all nine methods
6+
- **DT Coaching State** — Session persistence schema, method progress tracking, and session recovery protocol enabling the coach to resume seamlessly across conversations
67
- **DT Method Sequencing** — Governs the nine-method sequence across three spaces, space boundary transition protocols with readiness signals, non-linear iteration patterns, method routing logic, and coaching state tracking
78
- **DT Quality Constraints** — Quality constraints, fidelity rules, and output standards for Design Thinking coaching across all nine methods
89
- **DT Method 01: Scope Conversations** — Frozen vs fluid assessment, stakeholder discovery, constraint patterns, and conversation navigation for transforming initial customer requests into genuine understanding of business challenges

‎collections/design-thinking.collection.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ items:
1414
kind: instruction
1515
- path: .github/instructions/design-thinking/dt-quality-constraints.instructions.md
1616
kind: instruction
17+
- path: .github/instructions/design-thinking/dt-coaching-state.instructions.md
18+
kind: instruction
1719
- path: .github/instructions/design-thinking/dt-method-01-scope.instructions.md
1820
kind: instruction
1921
- path: .github/instructions/design-thinking/dt-method-02-research.instructions.md

‎collections/hve-core-all.collection.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,8 @@ items:
156156
kind: instruction
157157
- path: .github/instructions/design-thinking/dt-coaching-identity.instructions.md
158158
kind: instruction
159+
- path: .github/instructions/design-thinking/dt-coaching-state.instructions.md
160+
kind: instruction
159161
- path: .github/instructions/design-thinking/dt-method-01-scope.instructions.md
160162
kind: instruction
161163
- path: .github/instructions/design-thinking/dt-method-02-research.instructions.md

‎plugins/design-thinking/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ copilot plugin install design-thinking@hve-core
1616
| dt-coaching-identity | Required instructions when working with or doing any Design Thinking (DT); Contains instructions for the Design Thinking coach identity, philosophy, and user interaction and communication requirements for consistent coaching behavior. |
1717
| dt-method-sequencing | Method transition rules, nine-method sequence, space boundaries, and non-linear iteration support for Design Thinking coaching |
1818
| dt-quality-constraints | Quality constraints, fidelity rules, and output standards for Design Thinking coaching across all nine methods |
19+
| dt-coaching-state | Coaching state schema for Design Thinking session persistence, method progress tracking, and session recovery |
1920
| dt-method-01-scope | Method 1 Scope Conversations coaching knowledge for Design Thinking: frozen vs fluid assessment, stakeholder discovery, constraint patterns, and conversation navigation |
2021
| dt-method-02-research | Method 2 Design Research coaching knowledge: interview techniques, research planning, environmental observation, and insight extraction patterns |
2122
| dt-method-03-synthesis | Method 3 Input Synthesis coaching knowledge: pattern recognition, theme development, synthesis validation, and Problem-to-Solution Space transition readiness |

‎plugins/design-thinking/instructions/dt-coaching-state.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../.github/instructions/design-thinking/dt-coaching-state.instructions.md

‎plugins/hve-core-all/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ copilot plugin install hve-core-all@hve-core
9595
| terraform | Instructions for Terraform infrastructure as code implementation - Brought to you by microsoft/hve-core |
9696
| uv-projects | Create and manage Python virtual environments using uv commands |
9797
| dt-coaching-identity | Required instructions when working with or doing any Design Thinking (DT); Contains instructions for the Design Thinking coach identity, philosophy, and user interaction and communication requirements for consistent coaching behavior. |
98+
| dt-coaching-state | Coaching state schema for Design Thinking session persistence, method progress tracking, and session recovery |
9899
| dt-method-01-scope | Method 1 Scope Conversations coaching knowledge for Design Thinking: frozen vs fluid assessment, stakeholder discovery, constraint patterns, and conversation navigation |
99100
| dt-method-02-research | Method 2 Design Research coaching knowledge: interview techniques, research planning, environmental observation, and insight extraction patterns |
100101
| dt-method-03-synthesis | Method 3 Input Synthesis coaching knowledge: pattern recognition, theme development, synthesis validation, and Problem-to-Solution Space transition readiness |

‎plugins/hve-core-all/instructions/dt-coaching-state.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../.github/instructions/design-thinking/dt-coaching-state.instructions.md

0 commit comments

Comments
 (0)