gframework-doc-refresh

name

gframework-doc-refresh

description

Refresh or reassess GFramework documentation for a source module such as Core, Game, Godot, Cqrs, Ecs.Arch, or their generator/abstraction packages. Use this when the user asks to update module docs, re-evaluate landing pages, fix outdated topic pages, refresh API reference coverage, verify adoption paths against source/tests/README, or compare current docs with ai-libs consumer wiring. Recommended command: /gframework-doc-refresh <module>.

Purpose

Use this skill to refresh GFramework documentation from source-first evidence.

The public entry is module-driven, not doc-type-driven:

• Input: a source module or a resolvable docs section alias
• Output: the minimal documentation update set needed for that module
• Evidence: code, tests, README, current docs, then ai-libs/

Do not start by deciding “this is an API doc task” or “this is a tutorial task”. Decide that only after the module scan.

Triggers

Use this skill when the user asks things like:

• refresh docs for Core
• update Game module docs
• 根据 Godot 模块源码刷新文档
• 重新评估 Cqrs 模块文档并更新
• 核对 Godot.SourceGenerators 的文档状态
• 看看 source-generators 栏目哪些页面已经失真

Recommended command form:

/gframework-doc-refresh <module>

Supported Modules

Canonical module names:

• Core
• Core.Abstractions
• Core.SourceGenerators
• Core.SourceGenerators.Abstractions
• Game
• Game.Abstractions
• Game.SourceGenerators
• Godot
• Godot.SourceGenerators
• Godot.SourceGenerators.Abstractions
• Cqrs
• Cqrs.Abstractions
• Cqrs.SourceGenerators
• Ecs.Arch
• Ecs.Arch.Abstractions
• SourceGenerators.Common

The canonical mapping lives in .agents/skills/_shared/module-map.json.

If the user supplies a docs section name:

• resolve it back to a source module first
• if it maps to multiple modules, stop at normalization guidance and do not draft docs yet

Workflow

1. Normalize the input

Run:

python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py <module>

The script normalizes aliases, reports ambiguity, and prints the module's evidence surface.

If the result is ambiguous:

• return the candidate modules
• ask the user to pick the intended source module
• do not continue into document generation

2. Scan the evidence surface

For the resolved module, inspect:

• source directories
• *.csproj
• relevant test projects
• sibling README.md
• mapped docs/zh-CN landing pages and topic pages
• optional ai-libs/ consumer evidence when needed

Always confirm the actual files in the repository. Do not assume the mapping is enough on its own.

3. Decide whether ai-libs/ is needed

Use ai-libs/ when:

• adoption path is unclear from source and README alone
• extension points need a real consumer wiring example
• current docs have concepts but lack an end-to-end integration path

Do not rely on ai-libs/ for:

• public API contract definitions
• generator diagnostics or semantic guarantees
• claims about what the current version officially supports

If ai-libs/ conflicts with current source or tests, keep source/tests as the contract and document the migration boundary.

4. Judge the documentation state

Classify the module into one or more of these states:

• missing landing page
• stale landing page
• stale topic page
• missing or stale API reference coverage
• stale tutorial/example
• validation-only

Base this on evidence, not on the previous docs shape.

5. Choose the output set

Always prioritize:

1. README / landing page / adoption path
2. topic pages
3. API reference
4. tutorials

If the module only needs validation or relinking, do not generate extra pages.

6. Draft or update docs

Load only the template that matches the output you selected:

• templates/module-landing.md
• templates/topic-refresh.md
• templates/api-reference.md
• templates/tutorial.md

Keep examples minimal, current, and traceable to source or tests.

7. Validate

Run the internal validators as needed:

bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh <file-or-directory>

For site-level confirmation after doc edits:

cd docs && bun run build

Evidence Order

Use this exact priority:

1. source code, XML docs, *.csproj
2. tests and snapshots
3. module README.md
4. current docs/zh-CN pages
5. verified ai-libs/ consumers
6. archived docs only as fallback context

Output Rules

• Prefer correcting the adoption path over expanding page count.
• Do not copy wording from outdated docs just to keep page volume.
• Public docs must stay reader-facing. Do not write inventory, coverage baseline, recovery-point, batch-metric, review backlog, or audit-wave wording into README.md or docs/**.
• Use neutral, destination-first section names and link labels. Do not expose raw filenames or paths such as game/index.md, README.md, or ../core/cqrs.md as visible reader-facing labels when a semantic label is available.
• Do not use rhetorical or conversational headings in public docs, such as “你真正会用到的公开入口”、 “先理解包关系” or “想看……转到……”. Prefer direct labels such as “公开入口”、 “模块与包关系” and “相关主题”.
• Keep public docs out of internal product-decision tone. Do not publish repository-governance wording such as “当前阶段的结论”、“不建议立即启动” or audience-maintainer tradeoff discussions unless the page itself is a public adoption guide and the wording has been rewritten as reader-facing suitability guidance.
• If XML or audit evidence is relevant, translate it into reader guidance such as “which types to inspect first” or “which entry points define the contract”, instead of exposing counts, dates, or governance status.
• Escape generics outside code blocks.
• Keep internal links real and current.
• Mark code blocks with explicit languages.
• Use the smallest example that demonstrates the current contract.
• Consumer examples may align with ai-libs/, but must not exceed the current module contract.

Validation

Use the shared standards in .agents/skills/_shared/DOCUMENTATION_STANDARDS.md.

When this skill changes public docs, prefer:

1. focused validator on touched pages
2. cd docs && bun run build

When this skill changes the skill system itself:

1. validate SKILL.md frontmatter exists
2. run the module scan script for representative modules
3. confirm obsolete vitepress-* public entries are gone

References

Read these only when needed:

• .agents/skills/_shared/DOCUMENTATION_STANDARDS.md
• .agents/skills/_shared/module-map.json
• references/module-selection.md
• references/evidence-and-ai-libs.md
• references/output-strategy.md