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, and structuring clean commits. Counterpart of finalize-and-commit for documentation projects.
license	MIT
compatibility	["Claude Code","Cursor"]
metadata	{"type":"execution","category":"documentation","maturity":"stable","estimated_time":"15 min"}

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
• Prepare structured commits separated by change type

---

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 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)

---

Output Format

1. Convention Reference (discovered patterns)
2. Code-Documentation Alignment Report
3. Quality Review Findings
4. Actions Taken (auto-fixes applied)
5. Build Verification Results
6. Commit Plan
7. Final Commit Messages

---

Procedure

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: Since no formal style guide exists, infer conventions from existing documentation to use as the review baseline.

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)

---

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.
• 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"
• 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. Code-Documentation Alignment Report: skipped (no source code changes)
3. 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
4. Actions Taken: added sidebar_position: 1 to frontmatter, standardized "설정값" (no space, matching 80% of existing usage)
5. Build Verification: npm run build exit 0, no warnings
6. Commit Plan: 2 commits — (a) style fix, (b) new content
7. Final Commit Messages:
   • docs(style): standardize terminology and frontmatter in configuration page
   • docs(content): add getting started guide

---

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. 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)
3. 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
4. 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
5. Build Verification: npm run build exit 0, 1 warning (pre-existing, out of scope)
6. Commit Plan: 4 commits
7. 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

---

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.