docs-finalize-and-commit

name	docs-finalize-and-commit
description	Finalize documentation changes for production readiness by discovering existing conventions, verifying code-doc alignment, reviewing format/terminology/tone consistency, verifying branch/worktree intent, and structuring clean commits with a post-publish branch/worktree cleanup decision. Counterpart of finalize-and-commit for documentation projects.
license	MIT
metadata	{"compatibility":"Claude Code, Cursor","type":"execution","category":"documentation","maturity":"stable","estimated_time":"15 min","dependencies":"branch-context-check"}

Skill: Finalize Documentation and Commit (Review, Consistency, Alignment)

Type: Execution

Purpose

Finalize documentation changes for production readiness in a documentation project that coexists with the product source code in the same workspace. Works with any documentation framework (Docusaurus, VitePress, MkDocs, Nextra, plain Markdown, etc.).

Tasks:

• Discover conventions from existing documentation
• Verify code-documentation alignment when source code changed
• Review format, terminology, tone, and completeness consistency
• Validate framework-specific syntax and build integrity
• Verify current branch and dirty working tree match the intended documentation task
• Prepare structured commits separated by change type
• Force an explicit cleanup decision after push, PR creation, or PR merge

---

When to Use

• Before committing documentation changes to a shared branch
• Before submitting a pull request that includes documentation updates
• After completing a documentation session that touched multiple pages
• When source code and documentation were both modified in the same session
• When preparing a clean commit history from messy documentation edits
• When continuing documentation work after another session may have used the same repository

---

When NOT to Use

• Work-in-progress drafts still actively being written
• Trivial single-line typo fixes that need no consistency review
• Initial documentation scaffolding or exploratory writing phases
• Changes already reviewed and approved through another skill
• Standalone Markdown files outside a documentation project structure

---

Inputs Required

Do not run this skill without:

• Working tree with uncommitted or staged .md/.mdx file changes
• Access to the documentation project build command (if the framework provides one)
• Existing documentation files to derive conventions from (at least 3 pages)

Optional but recommended:

• Target branch context (e.g., main, release)
• List of intended change scope (files or directories)
• Known glossary or style guide (if any)
• Current task intent or expected branch/worktree name

---

Output Format

1. Convention Reference (discovered patterns)
2. Branch Context Verdict
3. Code-Documentation Alignment Report
4. Quality Review Findings
5. Actions Taken (auto-fixes applied)
6. Build Verification Results
7. Commit Plan
8. Final Commit Messages
9. Post-Publish Cleanup Decision

---

Procedure

Gate -1 – Branch Context Check

Run branch-context-check before validating the working set. If that skill is not installed, run the check inline: inspect git status --short --branch, git branch --show-current, git log --oneline --decorate -5, and the staged/dirty file lists, then classify the branch/worktree against the current documentation task using the same four verdicts below.

Required outcome:

• Current documentation task intent is summarized.
• Current branch, upstream state, recent commits, staged files, and dirty files are inspected.
• Branch/worktree verdict is one of match, ambiguous, mismatch, or blocked.

Proceed to Gate 0 only when:

• Verdict is match, or
• Verdict is ambiguous and the user explicitly confirms the branch/worktree is correct for the current documentation task.

Stop before staging or committing when:

• Verdict is mismatch or blocked.
• Staged files include changes outside the current documentation task.
• Dirty files from a previous session overlap with current-session documentation files.

In a stopped state, recommend a concrete recovery path: create/switch to a task-appropriate branch, create a separate worktree from the correct base, or finish/commit the previous-session work first. Do not move, stash, reset, or discard changes without explicit user approval.

---

Gate 0 – Working Set Validation

CRITICAL: The working tree may contain changes from other agent sessions or manual edits. This gate must isolate only the current session's changes without disturbing anything else.

Step 0-1: Identify current session scope

• Review the conversation history and edit history of this session.
• Build an explicit list of .md/.mdx files that were created, modified, or deleted by this session.
• Separately identify source code files changed in this session (needed for Gate 2).
• If the user provided a scope list, use that as the authoritative source.

Step 0-2: Inspect full working tree state

• Run git status and git diff --name-only to enumerate all uncommitted changes in the working tree.

Step 0-3: Classify changes

• Doc-scope: .md/.mdx files that appear in both the session scope (Step 0-1) and the working tree (Step 0-2).
• Code-scope: Source code files changed by this session (input for Gate 2).
• Out-of-scope: Files in the working tree NOT modified by this session.

Step 0-4: Protect out-of-scope changes

• NEVER revert, restore, checkout, stash, or discard out-of-scope changes.
• Out-of-scope files must be left exactly as they are in the working tree.
• The only correct action is to exclude them from staging (git add).

Step 0-5: Confirm with the user

• Present a summary:
  • Documentation files to be reviewed and committed (doc-scope)
  • Source code files to cross-reference (code-scope)
  • Files left untouched (out-of-scope), if any
• Proceed only after the user confirms the target set.

---

Gate 1 – Convention Discovery

PURPOSE: Establish the review baseline. Use a provided style guide first; infer conventions from existing documentation only where no explicit guidance exists.

Step 1-0: Use a provided style guide first

• If the user provided a style guide or glossary (see Optional inputs), treat it as the primary Convention Reference.
• Run Steps 1-1a–1-5 only to fill gaps the style guide does not cover (e.g., frontmatter fields, framework syntax), and never let inferred patterns override explicit style-guide rules.
• If the style guide fully covers structure, terminology, and tone, skip directly to Step 1-6.

Step 1-1a: Scan documentation headers

• Read frontmatter + first 30 lines of 10–15 representative .md/.mdx files from the docs directory (prioritize recently modified, high-traffic pages).
• If fewer than 10 documentation files exist, read all available files.
• Exclude files in the current session's change set to avoid circular reference.
• From this scan, extract: frontmatter field names, heading structure, first paragraph tone/speech level.

Step 1-1b: Deep read divergent samples

• Compare patterns extracted in Step 1-1a across all samples.
• Identify files where patterns diverge or are ambiguous (e.g., inconsistent frontmatter fields, mixed heading levels).
• Full-read only the divergent files (typically 2–5 files) to resolve ambiguity.
• If all samples show consistent patterns in Step 1-1a, skip this step.

Step 1-2: Extract structural patterns

• Frontmatter fields and their value patterns (title, sidebar_position, sidebar_label, description, tags, etc.)
• Heading level conventions (e.g., # for page title only, ## for top-level sections, ### for subsections)
• Common section ordering patterns (e.g., Overview → Usage → Configuration → Troubleshooting)

Step 1-3: Build terminology glossary

• Collect UI element names, feature names, and technical terms used consistently across existing pages.
• Note the canonical form for each term (e.g., "저장" not "저장하기", "Dashboard" not "대시보드" — or vice versa, depending on existing pattern).
• Record bilingual term pairs if the documentation uses a mixed-language convention (e.g., Korean prose with English UI labels).

Step 1-4: Identify tone and style

• Determine the dominant speech level (e.g., 합쇼체 ~합니다, 해요체 ~해요, 하십시오체 ~하십시오).
• Identify person/voice conventions (e.g., "사용자는 ~합니다" vs "~하세요" imperative).
• Note active vs passive voice preference.

Step 1-5: Identify documentation framework and catalog its conventions

• Detect the documentation framework in use by examining configuration files (e.g., docusaurus.config.js, .vitepress/config.*, mkdocs.yml, next.config.* for Nextra, or none for plain Markdown).
• Catalog framework-specific syntax patterns found in existing documentation:
  • Admonition/callout syntax (e.g., :::note in Docusaurus/VitePress, !!! note in MkDocs, > [!NOTE] in GitHub-flavored Markdown).
  • Component patterns (e.g., <Tabs>/<TabItem> in Docusaurus, custom MDX components in Nextra).
  • Code block language tags and annotation conventions.
  • Custom component or shortcode usage patterns.

Step 1-6: Compile Convention Reference

• Produce a structured summary to use as the review baseline in Gates 2–3.
• Present the Convention Reference to the user for confirmation before proceeding.

---

Gate 2 – Code-Documentation Alignment

ACTIVATION: This gate runs only if code-scope files were identified in Gate 0. If no source code changed, skip to Gate 3.

Step 2-1: Analyze source code changes

• Run git diff on code-scope files.
• Extract changed items: API endpoints, function signatures, component props, configuration keys, CLI commands, environment variables.

Step 2-2: Map code changes to documentation

• Search across all documentation files (not just in-scope) for references to the changed items using filename, import path, and keyword matching.
• Build a mapping: changed code item → documentation section(s) referencing it.

Step 2-3: Identify alignment gaps

Produce an alignment report with three categories:

• Already updated: Documentation section was modified in this session and reflects the code change.
• Needs update: Documentation references the changed code but was NOT updated in this session.
• No documentation found: Code change has no corresponding documentation (flag for user decision).

Present the report to the user. "Needs update" items must be resolved before proceeding — resolution means either updating the documentation OR the user explicitly acknowledging that no documentation change is needed (with reason).

---

Gate 3 – Documentation Quality Review

Apply the Convention Reference from Gate 1 to all doc-scope files.

3a) Structural consistency

• Heading levels follow the discovered convention.
• Frontmatter contains all expected fields with valid values.
• Section ordering matches the established pattern.
• No orphan headings (e.g., jumping from ## to ####).

3b) Terminology consistency

• Terms match the glossary from Gate 1.
• No mixed usage of the same concept (e.g., "저장" vs "저장하기", "Save" vs "세이브").
• Proper nouns, product names, and feature names are cased consistently.

3c) Tone and style consistency

• Speech level matches the discovered convention (no mixing 합쇼체 and 해요체 within the same page).
• Person/voice is consistent (imperative vs descriptive).
• No abrupt tone shifts between sections.

3d) Content completeness

• No TODO, TBD, FIXME, placeholder, or Lorem ipsum markers.
• No empty sections (heading followed immediately by another heading or EOF).
• No untranslated placeholder text if the documentation is localized.

3e) Framework-specific syntax validity

• Admonitions/callouts properly opened and closed per the framework's syntax.
• Framework-specific components have matching open/close tags and required attributes (if applicable).
• Code blocks have language tags and are properly fenced.
• MDX/component imports resolve to existing components (if applicable).
• Frontmatter YAML is valid (no syntax errors, no duplicate keys).

3f) Image and screenshot references

SKIP CONDITION: Skip if no image references (![, <img) exist in any doc-scope file. Verify with a quick text search before skipping.

• Every image reference (![alt](path) or <img src="path">) points to a file that exists in the repository.
• All images have non-empty alt text.
• No stale images (referenced file was deleted or moved).

3g) Link validity

• Internal document links (relative paths) resolve to existing files.
• Anchor links (#section-name) match actual heading slugs in the target document.
• No broken cross-references between documentation pages.

3h) Sidebar and navigation alignment

SKIP CONDITION: Skip if no files were added or deleted in this session (only modifications). Sidebar/nav changes are only relevant when the file set changes.

• Identify the sidebar/navigation configuration mechanism (e.g., sidebars.js in Docusaurus, _meta.json in Nextra, nav in mkdocs.yml, auto-generated from directory structure in VitePress).
• New documentation files added in this session are registered in the navigation configuration.
• Deleted documentation files are removed from the navigation configuration.
• Ordering metadata (e.g., sidebar_position in frontmatter, file ordering in config) does not conflict with other pages in the same category.

Produce a Quality Review Report organized by severity:

• Error: Must fix before commit (broken syntax, missing images, dead links).
• Warning: Should fix (terminology inconsistency, tone drift, missing alt text).
• Info: Optional improvement (section ordering, heading level suggestion).

---

Gate 4 – Auto-Fix

Step 4-1: Apply automatic fixes

Fix items that require no judgment:

• Terminology standardization (replace variant forms with canonical term)
• Heading level corrections
• Broken relative link path repair (if the correct target is deterministic)
• Missing frontmatter field population (using Convention Reference defaults)
• Admonition/code block syntax repair
• Remove TODO/placeholder markers in completed sections

Step 4-2: Present judgment-required items

Items that need user input:

• Content gaps identified in Gate 2 (code-doc alignment)
• Ambiguous terminology choices (when two forms are equally common)
• Tone corrections that alter meaning
• Missing images that need creation or replacement

Step 4-3: Summarize changes

• Present a before/after diff summary of all auto-fixes.
• Get user confirmation before proceeding.

---

Gate 5 – Build Verification

Step 5-1: Run documentation build

• Detect the build command from the project configuration (e.g., package.json scripts, Makefile, or framework CLI).
• Execute the build command from the documentation project root.
• Capture full output including warnings.

Step 5-2: Evaluate results

• Build succeeds with no warnings: Proceed to Gate 6.
• Build succeeds with warnings: Report warnings to user. Fix if they relate to in-scope files; proceed if warnings are pre-existing.
• Build fails: Analyze error, apply fix, return to Gate 4 Step 4-1.

Step 5-3: Record evidence

• Build pass = final proof that documentation syntax and link references are valid.
• Save build exit code and relevant output lines for the commit record.

---

Gate 6 – Commit Structuring

Staging rule: Stage only doc-scope files confirmed in Gate 0. Use git add <specific-file> for each file individually. Never use git add ., git add -A, or git add --all.

Step 6-1: Categorize changes

Group in-scope files by change type:

Change Type	Commit Prefix	Description
Error fixes	docs(fix):	Broken links, syntax errors, missing images
Style/format	docs(style):	Terminology, tone, heading, frontmatter normalization
Content update	docs(content):	New sections, rewritten paragraphs, expanded explanations
Code-sync	docs(sync):	Documentation updates reflecting source code changes

Step 6-2: Structure commits

• Create separate commits for each change type present.
• If a file has changes spanning multiple types, split by type where possible; otherwise, assign to the dominant change type.
• Ordering: docs(fix) → docs(style) → docs(content) → docs(sync).

Step 6-3: Write commit messages

Use Conventional Commits format. Each message must include:

• What changed (affected pages/sections)
• Why it changed (convention alignment, code-sync, error fix)
• Scope of review (mention Convention Discovery and build verification)

---

Gate 7 – Post-Publish Cleanup Handoff

After any commit, push, PR creation, or PR merge performed as part of this workflow, run Gate 6 of branch-context-check.

Required behavior:

• If only local commits were created, state whether push/PR is pending and what branch remains checked out.
• If a branch was pushed and the PR is still open, offer to keep the branch, switch back to base, or leave cleanup for after merge.
• If a PR was merged, offer or perform approved cleanup: switch to base, fast-forward pull, delete the local task branch, delete the remote task branch, prune remote refs, and prune stale worktree metadata.
• If a separate worktree was used, offer or perform approved worktree removal only after confirming that worktree is clean.

Do not end the workflow after push or merge without reporting the cleanup decision. Deletion still requires the safety checks from branch-context-check Gate 6 (inline fallback: delete only when the working tree is clean, the PR is merged or the user confirms the branch is obsolete, the branch is not the current checkout, and no other branch or worktree depends on it).

---

Guardrails

• Do not invent or fabricate documentation content not supported by the source code or existing documentation.
• Do not silence or bypass documentation build errors.
• Do not modify documentation tone or style without Convention Reference backing.
• Do not alter existing screenshots or images — only flag broken references.
• If context is insufficient to determine the correct term or phrasing, ask for clarification.
• Respect existing project conventions for commit messages and structure.
• Do not commit until branch/worktree intent has passed branch-context-check or the user has explicitly accepted an ambiguous verdict.
• Do not end after commit/push/merge without running the post-publish cleanup handoff.
• NEVER use git checkout -- <file>, git restore, git stash, git reset --hard, or any other command that discards or reverts uncommitted changes to files outside the current session's scope.
• NEVER use git add ., git add -A, or git add --all. Always stage files individually with git add <specific-file>.
• Working tree changes from other sessions, agents, or manual edits must be left completely untouched.
• Convention Discovery must sample from existing documentation only — never use in-scope changed files as convention sources.
• Do not auto-fix items that require content judgment (ambiguous terminology, meaning-altering tone changes) without user approval.

---

Failure Patterns

Common bad outputs:

• Applying conventions from only 1–2 sample files, producing biased standards
• Skipping Convention Discovery and inventing arbitrary style rules
• Ignoring code-documentation alignment when source code was also changed
• Lumping all documentation changes into a single undifferentiated commit
• Fixing terminology inconsistencies without checking which form is canonical in the existing corpus
• Running build verification in the wrong directory (product root instead of docs project root)
• Auto-fixing tone in a way that changes technical meaning
• Flagging pre-existing issues in files not modified by this session
• Reverting or discarding uncommitted changes that belong to other sessions
• Using git add . which accidentally stages out-of-scope changes
• Treating "ensure no unintended changes" as "revert unrelated files" instead of "exclude from staging"
• Continuing on a stale branch because documentation changes themselves look clean
• Treating a dirty previous-session branch as safe just because only doc files will be staged
• Pushing or merging successfully, then leaving stale local/remote branches or worktrees without offering cleanup choices
• Deleting branches or worktrees after merge without verifying clean state and merged/obsolete status
• Reporting Convention Reference without getting user confirmation, then applying incorrect standards

---

Example 1 (Minimal Context)

Input:

2 documentation files changed: a new "Getting Started" page was added, and an existing "Configuration" page had a section rewritten. No source code changes.

Output:

1. Convention Reference: frontmatter requires title, sidebar_position, description; headings use ## for top-level sections; tone is 합쇼체 (~합니다); admonitions use :::note and :::tip
2. Branch Context Verdict: match — current branch and doc-scope files align with the documentation task
3. Code-Documentation Alignment Report: skipped (no source code changes)
4. Quality Review Findings:
   • Error: new page missing sidebar_position in frontmatter
   • Warning: "Configuration" page mixes "설정값" and "설정 값" (spacing)
   • Info: "Getting Started" section order differs from convention
5. Actions Taken: added sidebar_position: 1 to frontmatter, standardized "설정값" (no space, matching 80% of existing usage)
6. Build Verification: npm run build exit 0, no warnings
7. Commit Plan: 2 commits — (a) style fix, (b) new content
8. Final Commit Messages:
   • docs(style): standardize terminology and frontmatter in configuration page
   • docs(content): add getting started guide
9. Post-Publish Cleanup Decision: not applicable yet — local commit only; push or PR cleanup will be decided after publish

---

Example 2 (Realistic Scenario)

Input:

8 documentation files changed across 3 categories (guides, API reference, troubleshooting). 4 source code files also changed, including a renamed API endpoint and a new configuration option. Sidebar configuration was not updated.

Output:

1. Convention Reference: frontmatter fields title, sidebar_position, sidebar_label, description, tags; 합쇼체 tone; features referenced with English name first then Korean in parentheses (e.g., "Dashboard (대시보드)"); :::warning for breaking changes, :::tip for best practices
2. Branch Context Verdict: match — branch name and dirty files align with docs/API synchronization
3. Code-Documentation Alignment Report:
   • Already updated: API reference page for renamed endpoint
   • Needs update: troubleshooting page still references old endpoint name; configuration guide missing new MAX_RETRY_COUNT option
   • No documentation: new internal helper function (no user-facing docs needed)
4. Quality Review Findings:
   • Error: 2 broken internal links (target files were reorganized last sprint)
   • Error: 1 image reference to deleted screenshot (old-dashboard.png)
   • Warning: API reference uses "대시보드" without English name (convention violation)
   • Warning: new guide page uses 해요체 ("~해요") while convention is 합쇼체
   • Info: 3 pages missing tags frontmatter field
5. Actions Taken: fixed 2 broken links, updated old endpoint references, added MAX_RETRY_COUNT documentation, standardized bilingual term format, corrected speech level to 합쇼체, added missing tags fields, registered new pages in sidebars.js, flagged missing screenshot for user replacement
6. Build Verification: npm run build exit 0, 1 warning (pre-existing, out of scope)
7. Commit Plan: 4 commits
8. Final Commit Messages:
   • docs(fix): repair broken links and remove stale image reference
   • docs(style): standardize terminology format and speech level across guides
   • docs(content): add MAX_RETRY_COUNT configuration documentation
   • docs(sync): update API reference and troubleshooting for endpoint rename
9. Post-Publish Cleanup Decision: after PR merge, offer switch-to-base, local/remote branch deletion, remote prune, and worktree prune; do not delete while the PR is still open

---

Notes

FAST MODE (only if explicitly requested):

• Gate 1 Convention Discovery limited to 5 most recent files
• Gate 3 performs only 3a (structural) and 3d (completeness) checks
• Gate 5 build verification skipped

Relationship with finalize-and-commit:

When both source code and documentation changed in the same session, run finalize-and-commit for source code first, then docs-finalize-and-commit for documentation. Gate 2 of this skill reads source code diffs but does not modify or commit source code files.