# Docs Impact Architect

Use this skill when the docs-impact-classifier returns a structural verdict, signalling...

- Repository: https://github.com/microsoft/apm (4171 stars)
- Category: Git and review
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add microsoft/apm --skill docs-impact-architect -g -a claude-code -y`
Codex: `npx skills add microsoft/apm --skill docs-impact-architect -g -a codex -y`
Cursor: `npx skills add microsoft/apm --skill docs-impact-architect -g -a cursor -y`
Gemini CLI: `npx skills add microsoft/apm --skill docs-impact-architect -g -a gemini-cli -y`

## Description

Use this skill when the docs-impact-classifier returns a structural verdict, signalling that the documentation TOC must change to accommodate the PR. Proposes TOC deltas (new pages, moves, merges) and emits new-page outline stubs that the doc-sync panel later fleshes out. Holds the 3-promise narrative (consume / produce / govern) and the persona ramps as hard constraints.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# docs-impact-architect

Single responsibility: when the classifier says a PR needs
structural docs changes (new page, page move, TOC reshape), design
the change and emit:

1. A precise TOC delta (added pages, moved pages, retired pages)
2. New-page outline stubs (slug, title, persona, promise, H2 sections, key examples)
3. The persona-ramp impact (which ramp gains/loses a stop)

You are NOT the writer (doc-writer owns prose). You are the **TOC
architect**. The CDO will arbitrate whether your proposal lands the
3-promise narrative; you do the first design pass.

## When to invoke

The docs-sync orchestrator invokes you ONLY when the classifier
returned `verdict: structural`. For `no_change` or `in_place` you
don't run.

## Inputs

- `structural_proposal` from the classifier (a sketch you refine)
- The PR diff (`gh pr diff $PR`)
- `.apm/docs-index.yml` (full corpus map)
- The PR description (for author-stated intent)

## Step 1: read the corpus map, not the corpus

Load `.apm/docs-index.yml` entirely. Inspect `chapters[]`, `pages[]`,
`promises[]`. This is your map. You do NOT read the 100+ page corpus
unless a specific page is implicated by the classifier's sketch.

## Step 2: classify the structural shape

Match the PR's surface change to one of these structural shapes:

The rest: https://github.com/microsoft/apm/blob/HEAD/.agents/skills/docs-impact-architect/SKILL.md