docs-impact-architect
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.
- License 许可
- MIT
- 所属仓库
- microsoft/apm
- 最近更新
- 2026-11-14
- Stars
- ★ 4.4k
- Forks
- 426
01 前言 Front Matter
- name
- docs-impact-architect
- 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.
02 资源文件 98
- 参考文档_meta.json138 B
- 参考文档.clawhub/origin.json151 B
- 资产文件assets/gep/capsules.json2.8 KB
- 资产文件assets/gep/genes.json3.7 KB
- 参考文档CONTRIBUTING.md327 B
- 脚本index.js30.4 KB
- 参考文档package.json986 B
- 参考文档README.md20.4 KB
- 参考文档README.zh-CN.md19.8 KB
- 脚本scripts/a2a_export.js2.3 KB
- 脚本scripts/a2a_ingest.js2.6 KB
- 脚本scripts/a2a_promote.js4.7 KB
- 脚本scripts/analyze_by_skill.js4.7 KB
- 脚本scripts/build_public.js10.6 KB
- 脚本scripts/extract_log.js2.5 KB
- 脚本scripts/generate_history.js2.5 KB
- 脚本scripts/gep_append_event.js3.0 KB
- 脚本scripts/gep_personality_report.js7.7 KB
- 脚本scripts/human_report.js5.7 KB
- 脚本scripts/publish_public.js19.9 KB
- 脚本scripts/recover_loop.js1.7 KB
- 脚本scripts/suggest_version.js3.0 KB
- 脚本scripts/validate-modules.js1.2 KB
- 脚本scripts/validate-suite.js1.8 KB
- 脚本src/canary.js486 B
- 脚本src/evolve.js82.4 KB
- 脚本src/gep/a2a.js6.3 KB
- 脚本src/gep/a2aProtocol.js27.8 KB
- 脚本src/gep/analyzer.js988 B
- 脚本src/gep/assetCallLog.js3.4 KB
- 脚本src/gep/assets.js1.1 KB
- 脚本src/gep/assetStore.js14.3 KB
- 脚本src/gep/bridge.js2.0 KB
- 脚本src/gep/candidateEval.js3.2 KB
- 脚本src/gep/candidates.js8.1 KB
- 脚本src/gep/contentHash.js2.1 KB
- 脚本src/gep/curriculum.js4.9 KB
- 脚本src/gep/deviceId.js6.6 KB
- 脚本src/gep/envFingerprint.js2.9 KB
- 脚本src/gep/executionTrace.js6.8 KB
- 脚本src/gep/gitOps.js7.8 KB
- 脚本src/gep/hubReview.js6.4 KB
- 脚本src/gep/hubSearch.js13.6 KB
- 脚本src/gep/idleScheduler.js5.4 KB
- 脚本src/gep/issueReporter.js8.8 KB
- 脚本src/gep/learningSignals.js2.9 KB
- 脚本src/gep/llmReview.js3.1 KB
- 脚本src/gep/memoryGraph.js26.9 KB
- 脚本src/gep/memoryGraphAdapter.js7.0 KB
- 脚本src/gep/mutation.js6.7 KB
- 脚本src/gep/narrativeMemory.js3.7 KB
- 脚本src/gep/paths.js3.9 KB
- 脚本src/gep/personality.js14.3 KB
- 脚本src/gep/policyCheck.js22.1 KB
- 脚本src/gep/prompt.js24.2 KB
- 脚本src/gep/questionGenerator.js8.5 KB
- 脚本src/gep/reflection.js6.0 KB
- 脚本src/gep/sanitize.js2.2 KB
- 脚本src/gep/selector.js16.0 KB
- 脚本src/gep/signals.js20.4 KB
- 脚本src/gep/skillDistiller.js50.1 KB
- 脚本src/gep/skillPublisher.js10.3 KB
- 脚本src/gep/solidify.js54.6 KB
- 脚本src/gep/strategy.js4.4 KB
- 脚本src/gep/taskReceiver.js17.3 KB
- 脚本src/gep/validationReport.js2.1 KB
- 脚本src/ops/cleanup.js2.5 KB
- 脚本src/ops/commentary.js1.7 KB
- 脚本src/ops/health_check.js4.0 KB
- 脚本src/ops/index.js376 B
- 脚本src/ops/innovation.js3.1 KB
- 脚本src/ops/lifecycle.js6.2 KB
- 脚本src/ops/self_repair.js2.5 KB
- 脚本src/ops/skills_monitor.js5.3 KB
- 脚本src/ops/trigger.js837 B
- 脚本test/a2aProtocol.test.js6.5 KB
- 脚本test/assetStore.test.js7.7 KB
- 脚本test/bench.test.js14.6 KB
- 脚本test/bridge.test.js4.5 KB
- 脚本test/candidates.test.js1.3 KB
- 脚本test/contentHash.test.js3.5 KB
- 脚本test/envFingerprint.test.js3.0 KB
- 脚本test/evolvePolicy.test.js1.3 KB
- 脚本test/hubEvents.test.js4.2 KB
- 脚本test/idleGating.test.js4.3 KB
- 脚本test/idleScheduler.test.js3.4 KB
- 脚本test/loopMode.test.js5.2 KB
- 脚本test/mutation.test.js4.6 KB
- 脚本test/paths.test.js8.8 KB
- 脚本test/prompt.test.js4.3 KB
- 脚本test/sanitize.test.js3.9 KB
- 脚本test/selector.test.js5.6 KB
- 脚本test/signals.test.js13.0 KB
- 脚本test/skillDistiller.test.js21.0 KB
- 脚本test/solidify-helpers.test.js12.6 KB
- 脚本test/solidifyLearning.test.js3.0 KB
- 脚本test/strategy.test.js4.8 KB
- 脚本test/validationReport.test.js4.8 KB
03 SKILL.md 正文
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:
- A precise TOC delta (added pages, moved pages, retired pages)
- New-page outline stubs (slug, title, persona, promise, H2 sections, key examples)
- 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_proposalfrom 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:
| 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.
Step 3: design the TOC delta
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
Step 4: validate against the 3-promise narrative
Apply these hard rules. If any fails, redesign:
- Every page belongs to exactly one promise. Cross-cutting pages (integrations, troubleshooting, reference) are explicitly marked
promise: cross. If a new page straddles two promises, split it OR park it undercross. - Consumer pages don't pre-teach producer concepts. A consumer page may LINK to producer; it may not embed producer prose.
- Producer pages don't pre-teach enterprise concepts. Same rule, one promise down.
- No page is orphaned from the TOC. Every new page has a
parent_chapterand at least oneincomingbridge. - No retired page lacks a
redirect_to. Search engines will index the old URL for months; the redirect is the SEO contract.
Step 5: emit the architect report
Return JSON:
{
"structural_shape": "NEW CAPABILITY" | "EXPANDED CAPABILITY" | "DEPRECATED CAPABILITY" | "CONCEPT SPLIT" | "CONCEPT MERGE" | "RAMP REORG",
"toc_delta": {
"new_pages": [...],
"moved_pages": [...],
"retired_pages": [...],
"chapter_changes": [...]
},
"promise_validation": {
"all_pages_single_promise": true | false,
"no_orphans": true | false,
"no_unredirected_retires": true | false,
"concerns": []
},
"downstream_in_place_pages": ["..."],
"rationale": "<2-3 sentence summary of why this structural delta and not alternatives>"
}
downstream_in_place_pages[] is the handoff to the localizer -- after
the architect approves the TOC, the localizer plans in-place edits
to existing pages that REFERENCE the new structure.
Output contract
Return a SINGLE JSON document matching the schema in Step 5 as the final message of your task. No prose around the JSON.
Anti-patterns
- Inflating new-page counts to seem thorough. The minimal true delta wins.
- Skipping the promise-validation step. The CDO will catch it; better to self-catch.
- Designing a new chapter when an existing chapter has room. Always prefer extending over creating.
- Forgetting
redirect_toon retired pages. SEO debt is the silent corpus killer.
04 同仓库更多 Skills
autopilot-issue-accept
Use this skill to accept ONE microsoft/apm issue with a declared scope. The canvas Accept button, or a maintainer asking to accept an issue, starts it. Draft only from the latest triage proposed scope, get exact-text approval in this chat from a GOVERNANCE roster human, post that comment as that human, then add status/accepted. Do not invent scope, do not accept pull requests, and do not implement the issue.
autopilot-issue-accept
Use this skill to accept ONE microsoft/apm issue with a declared scope. The canvas Accept button, or a maintainer asking to accept an issue, starts it. Draft only from the latest triage proposed scope, get exact-text approval in this chat from a GOVERNANCE roster human, post that comment as that human, then add status/accepted. Do not invent scope, do not accept pull requests, and do not implement the issue.
hello
暂无简介
placeholder
暂无简介
placeholder
暂无简介
placeholder
暂无简介