$ loading_
在文档结构需随 PR 调整时，规划目录变更并生成新页面大纲草案。
复制安装指令，让 AI 自动完成配置 · 推荐新手
请帮我安装 askskill 上的 "docs-impact-architect" 技能： 1. 下载 https://raw.githubusercontent.com/microsoft/apm/main/.apm/skills/docs-impact-architect/SKILL.md 2. 保存为 ~/.claude/skills/docs-impact-architect/SKILL.md 3. 装好后重载技能，告诉我可以用了
基于这次 PR 的结构性影响，提出文档目录调整方案：哪些页面需要新增、移动或合并，并为每个新增页面生成简要大纲。请严格遵守 consume / produce / govern 三段叙事和既定 persona ramps。
一份目录变更建议，包含新增、移动、合并页面清单，以及每个新页面的结构化大纲草案。
检查当前文档目录中与本次 PR 相关的入门内容，判断哪些页面应合并或重定位，以减少重复并保持用户路径清晰。同时输出合并后的目标页面大纲。
一份去重后的目录调整方案，说明合并原因、目标位置，以及合并后页面的大纲结构。
针对 PR 引入的新能力，设计需要新增的文档页面与目录位置，并输出每个页面的标题层级、核心内容点和与相邻页面的关系说明。
新增文档页面建议及其目录位置，并附带可供后续完善的页面骨架与内容要点。
Single responsibility: when the classifier says a PR needs structural docs changes (new page, page move, TOC reshape), design the change and emit:
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.
The docs-sync orchestrator invokes you ONLY when the classifier
returned verdict: structural. For no_change or in_place you
don't run.
structural_proposal from the classifier (a sketch you refine)gh pr diff $PR).apm/docs-index.yml (full corpus map)Load .apm/docs-index.yml entirely. Inspect , ,
. This is your map. You do NOT read the 100+ page corpus
unless a specific page is implicated by the classifier's sketch.
chapters[]pages[]promises[]Match the PR's surface change to one of these structural shapes:
| Shape | Pattern | Example |
|---|---|---|
| NEW CAPABILITY | A new CLI verb, primitive type, or schema concept the docs have no slot for | apm pack --format wheel adds a new package format |
| EXPANDED CAPABILITY | An existing concept grows in scope and the current page can't hold it | apm install gains a registry-proxy mode that needs its own sub-page |
| DEPRECATED CAPABILITY | A removed CLI verb, flag, or concept; existing pages need to be retired or rewritten | A flag is removed; tutorial pages still teach it |
| CONCEPT SPLIT | One concept becomes two distinct concepts; one page becomes two | apm audit splits into audit and audit ci |
| CONCEPT MERGE | Two concepts unify; two pages should become one | apm pack and apm bundle merge into one verb |
| RAMP REORG | The PR's surface change shifts a concept across promises (e.g. an enterprise feature becomes consumer-default) | Policy enforcement moves from enterprise to consumer default behaviour |
The structural shape drives the TOC delta shape.
For each new page proposed, fill in:
new_page:
slug: docs/src/content/docs/<persona>/<topic>.md
title: "<short imperative title>"
persona: consumer | producer | enterprise | cross
promise: 1 | 2 | 3 | cross
parent_chapter: <existing chapter slug>
h2_sections:
- "## Why <topic>" # OPTIONAL -- skip unless concept is genuinely new
- "## How to <use>" # REQUIRED -- code first
- "## Reference" # OPTIONAL -- flag/option table
- "## Troubleshooting" # OPTIONAL -- only if known footguns
bridges:
incoming: # which existing pages should link TO this
- {from: <slug>, link_text: <suggested>}
outgoing: # which existing pages should this link FROM
- {to: <slug>, link_text: <suggested>}
ramp_impact: >-
one-paragraph description of how this changes the <persona>
ramp: which step it slots into, whether it adds a stop or
replaces an existing one
For each moved/retired page:
moved_page:
from: <slug>
to: <slug>
redirect_rationale: <one-sentence>
retired_page:
slug: <slug>
reason: <one-sentence>
redirect_to: <slug> # MUST exist; orphaning pages breaks SEO
Apply these hard rules. If any fails, redesign:
promise: cross. If a new page straddles two promises, split it OR park it under cross.…
优化 APM 代码库中的 CLI 输出、日志提示与诊断信息体验
在每次 PR 变更时评估文档影响，并给出可落地的更新建议。