document（文档处理）

<tool_restrictions>

MANDATORY Tool Restrictions

BANNED TOOLS — calling these is a skill violation:

• EnterPlanMode — BANNED. Do NOT call this tool. This skill has its own documentation generation process. Claude's built-in plan mode would bypass it.
• ExitPlanMode — BANNED. You are never in plan mode. There is nothing to exit.

REQUIRED TOOLS:

• AskUserQuestion — Preserve the one-question-at-a-time interaction pattern for every user question, including clarifying scope, choosing audience, and validating content. In Claude Code, use the tool. In Codex, ask one concise plain-text question at a time unless a structured question tool is actually available in the current mode. This prevents walls of text with multiple questions. If you need to provide context before asking, keep it to 2-3 sentences max, and do not narrate missing tools or fallbacks to the user.

If you feel the urge to "plan before acting" — that urge is satisfied by following the <process> steps below. Execute them directly. </tool_restrictions>

<arc_runtime> This workflow requires the full Arc bundle, not a prompts-only install. Resolve the Arc install root from this skill's location and refer to it as ${ARC_ROOT}. Use ${ARC_ROOT}/... for Arc-owned files such as references/, disciplines/, agents/, templates/, and scripts/. Use project-local paths such as .ruler/ or rules/ for the user's repository. </arc_runtime>

<key_principles>

Key Principles

• One question at a time via the AskUserQuestion interaction pattern — In Claude Code, use the tool. In Codex, ask one concise plain-text question at a time unless a structured question tool is actually available in the current mode. Never ask more than one question per message, and do not narrate missing tools or fallbacks to the user.
• Substance before meta-decisions — Scan the codebase and show what you found BEFORE asking about audience, format, or location. Users decide better with concrete context.
• Framework-aware, not framework-coupled — Detect existing docs frameworks and generate in their format. If none exists, generate plain markdown and recommend one. Never install or scaffold frameworks.
• Incremental validation — Generate a sample section first. Get approval on style and depth before generating the rest.
• Respect existing docs — When docs already exist, offer to add to the existing structure rather than replacing everything.
• Code examples from source — Every code example in generated docs must come from actual source code, never fabricated. </key_principles>

<tasklist_context> Use TaskList tool to check for existing tasks related to documentation work.

If a related task exists, note its ID and mark it in_progress with TaskUpdate when starting. </tasklist_context>

<required_reading> Read these reference files NOW:

1. ${ARC_ROOT}/references/documentation-guide.md
2. ${ARC_ROOT}/templates/doc-templates.md </required_reading>

<progress_context> Use Read tool: docs/arc/progress.md (first 50 lines)

Check for recent documentation work or related changes. </progress_context>

Phase 1: Detect Intent & Context

Silently gather context (don't dump findings on the user):

1. Read package.json — identify stack, dependencies, project name
2. Scan directory structure — app/, pages/, src/, packages/
3. Check for existing docs — Glob docs/**/*.md, docs/**/*.mdx, content/**/*.md, content/**/*.mdx
4. Check for existing docs framework (see Framework Detection below)

Then determine intent from the user's input:

If user provided a file/directory path (e.g., /arc:document src/lib/auth.ts):

• Read the target file/directory
• Analyze: exports, types, dependencies, usage patterns
• Use AskUserQuestion: Question: "I see [file] exports [N] functions and [N] types. Should I..." Header: "Scope" Options: - label: "Document just this file" description: "Reference doc: exports, types, usage examples" - label: "Document the broader feature" description: "Feature guide: all related files, end-to-end"
• Route to Reference or Feature flow based on answer

If user provided a description (e.g., "document the auth feature"):

• Route to Feature flow

If user provided no args:

• Use AskUserQuestion: Question: "What would you like to document?" Header: "Scope" Options: - label: "A specific file or module" description: "I'll point you at a file and generate a reference doc" - label: "A feature" description: "End-to-end documentation for a feature across all its files" - label: "The entire project" description: "Full documentation site — I'll scan the codebase and generate everything"
• Route based on answer

Phase 2: Scope & Audience

Reference Flow

1. Read the target file completely
2. Analyze exports, types, interfaces, dependencies, imported-by relationships
3. Present findings: "[File] exports [list]. It depends on [list] and is used by [list]."
4. Ask audience via AskUserQuestion: Question: "Who is this documentation for?" Header: "Audience" Options: - label: "Developers" description: "How the code works: architecture, types, patterns, dependencies" - label: "Users" description: "How to use it: getting started, configuration, examples" - label: "Both" description: "Separate sections for developers and users"

Feature Flow

1. Identify all files that comprise the feature:

- Routes/pages related to it - API endpoints - Components - Types/interfaces - Utilities/helpers - Tests - Configuration

1. Present: "The [feature] spans [N] files: [list key files]"
2. If existing docs directory found, ask via AskUserQuestion: Question: "I see existing docs at [path]. Should I..." Header: "Existing docs" Options: - label: "Add to existing structure" description: "Create new doc files in the existing docs directory" - label: "Create standalone" description: "Generate docs in a new location"
3. Ask audience (same as Reference flow)

Full-Site Flow

1. Scan the codebase. Identify documentable units: What Detection Routes/Pages Glob app/, pages/, src/app/ API endpoints Glob api/ routes, server actions, tRPC routers Components Exported components with props/interfaces Packages packages/*/package.json in monorepos Configuration .env.example, config files, environment variables Database schema Drizzle schema files, Prisma schema Authentication Auth providers, middleware, protected routes CLI commands bin/ or command definitions
2. Generate an outline. Present it to the user: I found [N] routes, [N] API endpoints, [N] packages, and a [database] schema. Proposed documentation outline: 1. Getting Started 2. Features - Auth (5 files) - Billing (3 files) - Notifications (4 files) 3. API Reference - Users endpoint - Orders endpoint 4. Architecture - Overview 5. Reference - Components (12) - Utilities (8)
3. Ask for approval via AskUserQuestion: Question: "Does this outline look right?" Header: "Outline" Options: - label: "Yes, proceed" description: "Generate docs for all these sections" - label: "Remove some sections" description: "I'll tell you what to skip" - label: "Add something missing" description: "There's something I want documented that's not listed"
4. Ask audience (same question as Reference/Feature flow)

Phase 3: Framework Detection

Check package.json dependencies and project files:

If framework detected:

• Note the format silently
• Generate content in that format
• Detect existing content directory (e.g., content/docs/ for Fumadocs)

If no framework detected:

• Will generate plain markdown
• After sample validation, recommend a framework based on stack:

- Next.js project → "Fumadocs would give you search, navigation, and a polished UI. Set it up with /arc:implement?" - Astro project → "Starlight is built for Astro and gives you great docs out of the box." - General → "Plain markdown works everywhere. If you want a docs site later, Fumadocs or VitePress are good options."

• Use AskUserQuestion: Question: "No docs framework detected. Want to..." Header: "Format" Options: - label: "Plain markdown" description: "Simple.md files with a README index. Works everywhere." - label: "Set up a framework first" description: "I'll recommend one for your stack. Use /arc:implement to scaffold it, then come back."

Phase 4: Sample & Validation

Before generating all docs, produce one sample section.

Pick the most representative section from the outline (or the target for Reference/Feature flow). Generate it fully.

Show the sample to the user, then ask via AskUserQuestion:

Question: "Here's the [section name] documentation. Is the depth and style right?"
Header: "Style check"
Options:
  - label: "Yes, generate the rest"
    description: "This depth and tone is what I want"
  - label: "More detailed"
    description: "Include more technical depth, more examples"
  - label: "Less detailed"
    description: "Keep it higher-level, less verbose"
  - label: "Different tone"
    description: "I'll describe what I want changed"

If user wants changes: adjust and regenerate the sample. Repeat until approved.

This validated sample becomes the style reference for all subsequent generation (and for docs-writer agents in full-site mode).

Phase 5: Location

Determine where docs should live.

If existing docs directory was found in Phase 1, propose using it.

Otherwise, ask via AskUserQuestion:

Question: "Where should the docs live?"
Header: "Location"
Options:
  - label: "docs/"
    description: "Standard convention at the repo root"
  - label: "apps/docs/content/"
    description: "Monorepo convention — docs as a separate app"

For Fumadocs projects, check source.config.ts for the configured content directory and use that.

Phase 6: Generation

Reference & Feature (small scope)

Single-pass generation. No agents needed.

1. Use the templates from ${ARC_ROOT}/templates/doc-templates.md
2. Read all source files identified in Phase 2
3. Generate documentation matching the validated style sample
4. Write files to the chosen location
5. If framework detected, generate sidebar config (meta.json, _meta.json, etc.)

Full-Site (large scope)

Spawn docs-writer agents in batches following ${ARC_ROOT}/disciplines/dispatching-parallel-agents.md.

1. Prepare agent assignments. Each outline section = one agent. Each agent gets:

- Section name and description - List of source files to read (exact paths) - Audience: developer, user, or both - The validated style sample from Phase 4 - Output format: .md or .mdx - Framework-specific instructions (sidebar config format, frontmatter requirements) - Output location

1. Dispatch in batches of 2-3. Batch 1: Agent → Features/Auth, Agent → Features/Billing Batch 2: Agent → API Reference, Agent → Architecture Batch 3: Agent → Components Reference, Agent → Getting Started
2. Collect results. Each agent returns file contents in delimiter format.
3. Write files. Create the directory structure and write each file.

Phase 7: Consolidation (full-site only)

After all agents return:

1. Terminology check — Scan all generated docs for the same concept called different names. Standardize.
2. Cross-reference check — Verify all internal links ([see auth](../features/auth.md)) point to real files.
3. Gap check — Compare generated docs against the outline. Flag any missing sections.
4. Fix issues — Rewrite affected sections. Don't rewrite everything.

Phase 8: Supporting Files

Generate supporting infrastructure:

For plain markdown:

• README.md — Index with links to all sections, using the full-site index template
• getting-started.md — Quick start guide (if full-site mode)

For Fumadocs:

• meta.json in each directory — sidebar ordering
• Root index.mdx — Landing page
• getting-started.mdx — Quick start guide (if full-site mode)

For Nextra:

• _meta.json in each directory

For other frameworks:

• Appropriate sidebar/navigation config

Completion

Present what was generated:

Documentation generated:

Files: [N] docs written
Location: [path]
Format: [markdown / Fumadocs MDX / etc.]
Audience: [developer / user / both]

Sections:
- Getting Started
- Features: Auth, Billing, Notifications
- API Reference: Users, Orders
- Architecture: Overview
- Reference: Components, Utilities

Then offer next steps via AskUserQuestion:

Question: "What's next?"
Header: "Next step"
Options:
  - label: "Review the docs"
    description: "I'll walk through each section for your approval"
  - label: "Add more sections"
    description: "Document additional features or modules"
  - label: "Set up a docs framework"
    description: "Scaffold a docs site with /arc:implement to host these"
  - label: "Done"
    description: "Documentation is complete"

Doc staleness detection: /arc:implement checks for stale docs after completing work. If changed files have associated documentation, they prompt the user to update inline.

Production readiness: /arc:letsgo includes documentation coverage as a checklist item.

Design context: /arc:ideate reads existing docs to understand the current feature set.

Framework scaffolding: If the user wants a docs site (Fumadocs, etc.), route them to /arc:implement for the infrastructure. /arc:document generates content, not apps.

<arc_log> After completing this skill, append to the activity log. See: ${ARC_ROOT}/references/arc-log.md

Entry: /arc:document — [scope] ([audience]) [N files]

Examples:

• /arc:document — auth.ts reference (developer) 1 file
• /arc:document — auth feature guide (user) 3 files
• /arc:document — full site (both) 24 files </arc_log>

<success_criteria> Documentation is complete when:

• Intent detected from user input (reference, feature, or full-site)
• Codebase scanned and findings shown to user
• Audience selected (developer, user, both)
• Framework detected (or plain markdown chosen)
• Sample section generated and style approved by user
• All documentation files written to chosen location
• Sidebar/navigation config generated (if framework detected)
• Index/README generated with links to all sections
• Cross-references verified (full-site only)
• User presented with completion summary and next steps </success_criteria>