docs-finalize-and-commit

# 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.