Skip to content

docs: Update RAI Planner docs for Phase 1 preflight, phaseGates, and template-aware resume #2888

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Bill Berry (WilliamBerryiii) merged 6 commits into from
Sep 14, 2026
+79 −60
Merged

docs: Update RAI Planner docs for Phase 1 preflight, phaseGates, and template-aware resume #2888

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2112e1e
docs: Update RAI Planner docs for Phase 1 preflight, phaseGates, and …
PratikWayase Sep 10, 2026
8ef4863
Merge branch 'main' into docs/rai-planner-phase1-updates-2865
WilliamBerryiii Sep 10, 2026
61db12f
Merge branch 'main' into docs/rai-planner-phase1-updates-2865
WilliamBerryiii Sep 11, 2026
25b82c1
fix failed ci jobs
PratikWayase Sep 11, 2026
742a668
Merge branch 'docs/rai-planner-phase1-updates-2865' of https://github…
PratikWayase Sep 11, 2026
63a97a3
Merge branch 'main' into docs/rai-planner-phase1-updates-2865
WilliamBerryiii Sep 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 38 additions & 31 deletions docs/agents/rai-planning/agent-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ tags:
- architecture
- reference
author: Microsoft
ms.date: 2026-08-20
ms.date: 2026-09-10
ms.topic: reference
estimated_reading_time: 7
---
Expand Down Expand Up @@ -72,30 +72,33 @@ All assessment state persists under `.copilot-tracking/rai-plans/{project-slug}/

### State Fields

| Field | Type | Purpose |
|--------------------------------|----------------|---------------------------------------------------------------------------------|
| `projectSlug` | string | Kebab-case project identifier |
| `raiPlanFile` | string | Path to the RAI plan markdown file |
| `currentPhase` | number | Current phase (1-6) |
| `entryMode` | string | `capture`, `from-prd`, or `from-security-plan` |
| `disclaimerShownAt` | string or null | ISO 8601 timestamp when the disclaimer was displayed |
| `securityPlanRef` | string or null | Path to security plan state when using `from-security-plan` |
| `assessmentDepth` | string | Assessment tier (`Basic`, `Standard`, or `Comprehensive`) |
| `riskClassification` | object | Phase 2 risk classification results including `suggestedDepthTier` |
| `standardsMapped` | boolean | Whether Phase 3 mapping is complete |
| `securityModelAnalysisStarted` | boolean | Whether Phase 4 analysis has begun |
| `raiThreatCount` | number | Running count of identified RAI threats |
| `impactAssessmentGenerated` | boolean | Whether Phase 5 assessment is complete |
| `evidenceRegisterComplete` | boolean | Whether evidence register is finalized |
| `handoffGenerated` | object | Dual-format handoff status (`{ "ado": false, "github": false }`) |
| `gateResults` | object | Gate outcomes for threat coverage |
| `runningObservations` | array | Cross-phase observation log with phase number, observation text, and flag level |
| `principleTracker` | object | Per-principle coverage status, threat counts, and open observations |
| `referencesProcessed` | array | Files that have been read and incorporated |
| `nextActions` | array | Pending action items for the current phase |
| `signingRequested` | boolean | Whether artifact signing was requested |
| `signingManifestPath` | string or null | Path to the signing manifest file |
| `userPreferences` | object | User-specified preferences for interaction and output |
| Field | Type | Purpose |
|--------------------------------|----------------|------------------------------------------------------------------------------------|
| `projectSlug` | string | Kebab-case project identifier |
| `raiPlanFile` | string | Path to the RAI plan markdown file |
| `currentPhase` | number | Current phase (1-6) |
| `entryMode` | string | `capture`, `from-prd`, or `from-security-plan` |
| `preflight` | object | Phase 1 preflight data: `templates` array and `assessmentContentFile` string |
| `disclaimerShownAt` | string or null | ISO 8601 timestamp when the disclaimer was displayed |
| `noticeLog` | array | Log of disclaimers, attribution notices, and exit reminders |
| `phaseGates` | object | Per-phase gate type (`hard` vs `summary-and-advance`) and `confirmedAt` timestamps |
| `securityPlanRef` | string or null | Path to security plan state when using `from-security-plan` |
| `assessmentDepth` | string | Assessment tier (`Basic`, `Standard`, or `Comprehensive`) |
| `riskClassification` | object | Phase 2 risk classification results including `suggestedDepthTier` |
| `standardsMapped` | boolean | Whether Phase 3 mapping is complete |
| `securityModelAnalysisStarted` | boolean | Whether Phase 4 analysis has begun |
| `raiThreatCount` | number | Running count of identified RAI threats |
| `impactAssessmentGenerated` | boolean | Whether Phase 5 assessment is complete |
| `evidenceRegisterComplete` | boolean | Whether evidence register is finalized |
| `handoffGenerated` | object | Dual-format handoff status (`{ "ado": false, "github": false }`) |
| `gateResults` | object | Gate outcomes for threat coverage |
| `runningObservations` | array | Cross-phase observation log with phase number, observation text, and flag level |
| `principleTracker` | object | Per-principle coverage status, threat counts, and open observations |
| `referencesProcessed` | array | Files that have been read and incorporated |
| `nextActions` | array | Pending action items for the current phase |
| `signingRequested` | boolean | Whether artifact signing was requested |
| `signingManifestPath` | string or null | Path to the signing manifest file |
| `userPreferences` | object | User-specified preferences for interaction and output |

### Six-Step State Protocol

Expand Down Expand Up @@ -132,19 +135,23 @@ When returning to an existing RAI assessment, the agent follows a five-step resu
1. Read `state.json` from the project slug directory
2. If `disclaimerShownAt` is `null`, display the Startup Announcement verbatim and record the timestamp
3. Display current phase progress and checklist status
4. Summarize what was completed and what remains
4. Read persisted preflight state and perform validation:
* Revalidate every template by kind before dereferencing it. For documents, normalize the stored workspace-relative path, resolve it against the workspace root, and reject it when the result escapes the workspace. For Mural, accept only the stored opaque ID and keep authentication in the tool boundary.
* When templates is non-empty, verify the required assessmentContentFile; if it is missing or unusable, pause phase work and recreate it from every validated template, the authoritative rai-plan.md, and each template's local stableIdMap. Require every local map to be non-empty, one-to-one, and consistent with reconstructed content. If a local map is absent, empty, non-bijective, or conflicting, obtain confirmation before issuing replacement IDs.
* Stop and ask the user if validation or recreation fails. When templates is empty, require a null content file. Summarize what was completed and what remains.
5. Continue from the last incomplete action

### Post-Summarization Recovery

When conversation context is compacted, a six-step recovery process reconstructs state:
When conversation context is compacted, a seven-step recovery process reconstructs state:

1. Read `state.json` for project slug and current phase
2. If `disclaimerShownAt` is `null`, display the Startup Announcement verbatim and record the timestamp
3. Read the RAI plan markdown file referenced in `raiPlanFile`
4. Reconstruct context from existing artifacts (system definition pack, standards mapping, security model addendum, and control surface catalog)
5. Identify the next incomplete task within the current phase
6. Resume with a brief summary of recovered state and the next action
3. Run the complete Session Resume step 4 preflight validation and recovery contract, including the empty-template/null-content requirement, before reconstructing context or resuming the next task
4. Read the RAI plan markdown file referenced in `raiPlanFile`
5. Reconstruct context from existing artifacts (system definition pack, standards mapping, security model addendum, and control surface catalog)
6. Identify the next incomplete task within the current phase
7. Resume with a brief summary of recovered state and the next action

> [!NOTE]
> The disclaimer and attribution notices described above are conversational, displayed in the chat interface during session starts, resumes, and exit points. Generated artifacts in Phases 5 and 6 carry separate persisted footers (AI-content transparency notes, human review checkboxes, and full disclaimers on handoff deliverables) written directly into the markdown files. See [Handoff Pipeline](handoff-pipeline#artifact-attribution-and-review) for details on persisted artifact footers.
Expand Down
29 changes: 15 additions & 14 deletions docs/agents/rai-planning/entry-modes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ tags:
- rai-planning
- how-to
author: Microsoft
ms.date: 2026-06-27
ms.date: 2026-09-10
ms.topic: how-to
estimated_reading_time: 5
---
Expand All @@ -25,10 +25,11 @@ Use capture mode when starting a Responsible AI assessment from scratch with no
### How It Works

1. Provide an optional project slug or let the agent derive one from your project name
2. The agent creates `.copilot-tracking/rai-plans/{project-slug}/` and initializes `state.json` with `entryMode: "capture"` and `currentPhase: 1`
3. Phase 1 begins with up to 7 questions covering: AI system purpose, technology stack, model types, stakeholder roles, data inputs and outputs, deployment model, and intended use context
4. Answer questions conversationally; use "skip" or "n/a" for items that do not apply
5. The agent summarizes findings and asks for confirmation before advancing to Phase 2
2. The agent resolves attached-material pointers and output preferences
3. The agent creates `.copilot-tracking/rai-plans/{project-slug}/` and initializes `state.json` with `entryMode: "capture"` and `currentPhase: 1`, then enters the Phase 1 preflight
4. After preflight and reference discovery, Phase 1 begins with up to 7 questions covering: AI system purpose, technology stack, model types, stakeholder roles, data inputs and outputs, deployment model, and intended use context
5. Answer questions conversationally; use "skip" or "n/a" for items that do not apply
6. The agent summarizes findings and asks for confirmation before advancing to Phase 2

Prompt file: `.github/prompts/rai-planning/rai-capture.prompt.md`

Expand All @@ -47,11 +48,10 @@ Use from-prd mode when product requirements documents or business requirements d

### How It Works

1. The agent scans `.copilot-tracking/prd-sessions/` and `.copilot-tracking/brd-sessions/` for artifacts
2. If the primary scan finds nothing, a secondary scan searches `.copilot-tracking/` for files matching PRD or BRD naming patterns
3. Discovery results are presented for your confirmation with ✅ (valid) and ❌ (false positive) markers
4. The agent extracts AI system scope, stakeholders, data classification, and technology stack from confirmed artifacts
5. Phase 1 begins with pre-populated fields; the agent asks clarifying questions targeting gaps in the extracted information
1. The agent resolves the PRD pointer and output preferences
2. The agent creates `.copilot-tracking/rai-plans/{project-slug}/` and initializes `state.json` with `entryMode: "from-prd"` and `currentPhase: 1`, then enters the Phase 1 preflight
3. During project-material discovery in the preflight, the agent reads the PRD and extracts AI system scope, technology stack, model types, deployment model, and stakeholders
4. Phase 1 begins with pre-populated fields; the agent asks clarifying questions targeting gaps in the extracted information

Prompt file: `.github/prompts/rai-planning/rai-plan-from-prd.prompt.md`

Expand All @@ -69,10 +69,11 @@ Use from-security-plan mode after completing a security plan with the Security P

### How It Works

1. The agent reads the security plan `state.json` from the path specified in the prompt or from the most recent security plan in `.copilot-tracking/security-plans/`
2. AI components from the security plan's `aiComponents` array are pre-populated into the RAI assessment scope
3. Threat IDs start at the next sequence after the security plan's threat count, maintaining continuity across both assessments
4. Phase 1 begins with pre-populated AI element inventory; the agent asks targeted questions about RAI-specific aspects not covered in the security plan
1. The agent validates the security-plan pointer and resolves output preferences
2. The agent creates `.copilot-tracking/rai-plans/{project-slug}/` and initializes `state.json` with `entryMode: "from-security-plan"` and `currentPhase: 1`, then enters the Phase 1 preflight
3. During project-material discovery in the preflight, the agent reads the security plan `state.json` and extracts AI components from its `aiComponents` array
4. Threat IDs start at the next sequence after the security plan's threat count, maintaining continuity across both assessments
5. Phase 1 begins with pre-populated AI element inventory; the agent asks targeted questions about RAI-specific aspects not covered in the security plan

Prompt file: `.github/prompts/rai-planning/rai-plan-from-security-plan.prompt.md`

Expand Down
Loading
Loading