Back to Details

fix-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/fix-docs

/fix-docs

Fix the highest priority documentation gap.
修复优先级最高的文档缺口。

What This Does

功能说明

  1. Invoke 
    /check-docs
    to audit documentation
  2. Identify highest priority gap
  3. Fix that one issue
  4. Verify the fix
  5. Report what was done
This is a fixer. It fixes one issue at a time. Run again for next issue. Use 
/documentation
for full setup.
  1. 调用 
    /check-docs
    审核文档
  2. 识别优先级最高的缺口
  3. 修复该问题
  4. 验证修复效果
  5. 报告处理内容
这是一个修复工具。每次仅修复一个问题。如需处理下一个问题，请再次运行。使用 
/documentation
进行完整设置。

Process

处理流程

1. Run Primitive

1. 运行基础工具

Invoke 
/check-docs
skill to get prioritized findings.
调用 
/check-docs
技能获取按优先级排序的问题结果。

2. Fix Priority Order

2. 修复优先级顺序

Fix in this order:
  1. P0: Missing README.md, missing .env.example
  2. P1: README sections, undocumented env vars, architecture
  3. P2: Stale docs, CONTRIBUTING.md, ADRs
  4. P3: Polish, extras
按以下顺序修复：
  1. P0：缺少README.md、缺少.env.example
  2. P1：README章节缺失、环境变量未文档化、架构文档缺失
  3. P2：文档过时、缺少CONTRIBUTING.md、ADRs
  4. P3：文档优化、额外内容

3. Execute Fix

3. 执行修复

Missing README.md (P0): Generate README with proper structure:
  • Project name and tagline
  • What it does (one paragraph)
  • Quick Start (3 commands max)
  • Configuration (env vars)
  • Development commands
  • License
Delegate to Codex or write directly.
Missing .env.example (P0):
bash
undefined
缺少README.md（P0）： 生成结构规范的README：
  • 项目名称和标语
  • 功能介绍（一段文字）
  • 快速开始（最多3条命令）
  • 配置（环境变量）
  • 开发命令
  • 许可证
委托Codex生成或直接编写。
缺少.env.example（P0）：
bash
undefined

Scan for env vars and create .env.example

Scan for env vars and create .env.example

grep -rhoE "process.env.[A-Z_]+" --include=".ts" --include=".tsx" src/ app/ 2>/dev/null |
sort -u | sed 's/process.env.//' |
awk '{print $1"="}' > .env.example

**README missing sections (P1):**
Add the missing section with appropriate content.

**Undocumented env vars (P1):**
Add missing vars to .env.example with comments.

**Missing architecture docs (P1):**
Invoke `/cartographer` to generate CODEBASE_MAP.md.

**Stale documentation (P2):**
Review and update outdated content.
grep -rhoE "process.env.[A-Z_]+" --include=".ts" --include=".tsx" src/ app/ 2>/dev/null |
sort -u | sed 's/process.env.//' |
awk '{print $1"="}' > .env.example

**README章节缺失（P1）：**
添加缺失的章节及对应内容。

**环境变量未文档化（P1）：**
将缺失的变量添加到.env.example并附上注释。

**缺少架构文档（P1）：**
调用 `/cartographer` 生成CODEBASE_MAP.md。

**文档过时（P2）：**
审核并更新过时内容。

4. Verify

4. 验证

After fix:
bash
undefined
修复完成后：
bash
undefined

Verify file exists

Verify file exists

[ -f "README.md" ] && echo "✓ README exists" [ -f ".env.example" ] && echo "✓ .env.example exists"
[ -f "README.md" ] && echo "✓ README exists" [ -f ".env.example" ] && echo "✓ .env.example exists"

Verify content

Verify content

grep -q "## Installation" README.md && echo "✓ Has installation" grep -q "## Quick Start" README.md && echo "✓ Has quick start"
undefined
grep -q "## Installation" README.md && echo "✓ Has installation" grep -q "## Quick Start" README.md && echo "✓ Has quick start"
undefined

5. Report

5. 报告

Fixed: [P0] Missing README.md

Created README.md with:
- Project description
- Quick start guide
- Environment setup
- Development commands

Next highest priority: [P1] Missing .env.example
Run /fix-docs again to continue.
Fixed: [P0] Missing README.md

Created README.md with:
- Project name and tagline
- What it does (one paragraph)
- Quick Start (3 commands max)
- Configuration (env vars)
- Development commands
- License

Next highest priority: [P1] Missing .env.example
Run /fix-docs again to continue.

Branching

分支管理

Before making changes:
bash
git checkout -b docs/fix-$(date +%Y%m%d)
进行修改前：
bash
git checkout -b docs/fix-$(date +%Y%m%d)

Single-Issue Focus

单问题聚焦

This skill fixes one issue at a time. Benefits:
  • Small, reviewable changes
  • Easy to revert if needed
  • Clear commit history
  • Predictable behavior
Run 
/fix-docs
repeatedly to work through the backlog.
该技能每次仅修复一个问题。优势包括：
  • 改动小，便于审核
  • 如需回滚操作简单
  • 提交历史清晰
  • 行为可预测
重复运行 
/fix-docs
以处理所有待解决问题。

Related

相关工具

  • /check-docs
    - The primitive (audit only)
  • /log-doc-issues
    - Create issues without fixing
  • /documentation
    - Full documentation workflow
  • /cartographer
    - Generate architecture docs
  • /check-docs
    - 基础工具（仅审核）
  • /log-doc-issues
    - 仅记录问题不修复
  • /documentation
    - 完整文档工作流
  • /cartographer
    - 生成架构文档