Product Acceptance Doc

Product Acceptance HTML Document

Use this skill when the user wants a product-side document generated from git commits, especially when they provide a starting commitId.

Input Modes

Support four input modes.

1. Start Commit Mode

The user provides only a starting commit id. Interpret the range as:

<commitId>^..HEAD

This includes the starting commit through current HEAD. If the user explicitly asks to exclude the starting commit, use <commitId>..HEAD instead.

Example user request:

$product-acceptance-doc 5cdcf0f8019908184375709b0e0c85bb85cc2fb0

2. Explicit Range Mode

The user provides a git range. Use it exactly as provided after validating both sides when possible.

Examples:

$product-acceptance-doc range abc123..def456
$product-acceptance-doc range abc123^..HEAD

Use this mode when the user wants documentation for a known merge range, release range, or custom comparison.

3. Main Merge Mode

The user asks for a document after merging into main, and provides the previous main commit and the current merged main commit.

Example:

$product-acceptance-doc main-merge
previousMainCommit: abc123
currentMainCommit: def456

Interpret the range as:

abc123..def456

This excludes the previous main commit itself and includes all commits introduced up to the current merged commit. This is the preferred mode for “上一次 main 到本次 main 合并后”的 product acceptance documentation.

If the user asks for main merge mode but does not provide both commits, do not guess silently. First try to discover reliable candidates with:

git reflog main --date=iso
git log --oneline --decorate main -20
git branch --show-current
git rev-parse --short HEAD

Then either:

• use the clearly identifiable range if the reflog unambiguously shows the prior and current main positions, or
• ask the user for previousMainCommit and currentMainCommit.

4. Main Latest Mode

The user asks to generate a document from the latest two commits on main, usually after a branch has just been merged into main.

Example:

$product-acceptance-doc main-latest

Resolve the latest two first-parent commits on main:

git fetch origin main
git rev-list --first-parent --max-count=2 main

If local main is stale or absent, use origin/main after fetch:

git rev-list --first-parent --max-count=2 origin/main

Interpret the range as:

<previousMainCommit>..<currentMainCommit>

Use --first-parent because the product document should summarize what the latest merge introduced to main, not every side-branch ancestry detail. If the latest two first-parent commits do not represent the intended merge boundary, stop and ask the user for an explicit range or previousMainCommit/currentMainCommit.

Required Workflow

1. Resolve the commit range from the selected input mode. Store it mentally as <range>.

2. Confirm commits exist where applicable:

   git cat-file -t <commit>
   

3. Gather source evidence before writing:

   git status --short
   git log --reverse --format='%h%x09%ad%x09%s' --date=format:'%Y%m%d' <range>
   git diff --stat <range>
   git diff --name-only <range>
   

4. Read key changed files and diffs. Do not summarize only from commit messages.

   Prioritize files in:

   • src/views/**
   • src/components/**
   • src/api/**
   • src/lang/**
   • src/layout/**
   • src/store/**
   • src/utils/**
   • docs/**
   • build/CI files if changed

5. Identify product-visible changes:

   • New pages, tabs, workflows, buttons, filters, tables, dialogs, states
   • Changed defaults, navigation, layout, copy, permissions, language behavior
   • API/data changes that affect product behavior
   • Hidden/removed areas that product should not expect to see
   • Edge cases and regression areas product should test

6. If git status --short shows uncommitted changes, mention in the document that the document only covers committed changes in the requested range and does not include uncommitted worktree changes.

Output File

Create one directly openable HTML file:

docs/acceptance/YYYY-MM-DD-system-change-acceptance.html

If that filename already exists and the user did not ask for a new version, update it in place.

HTML Style

Use the product release-note layout:

• Dark background
• Fixed or sticky left module navigation
• Central article content
• Right page navigation
• Main content grouped by commit dates in descending order
• Each release section starts with:
  • 发布日期：YYYYMMDD
  • 概述
  • product/system name or affected module
• Each concrete change point contains:
  • 改了什么
  • 产品怎么验
  • affected page/module/API when relevant

Make it read like a product update page, not a technical diff report.

Content Rules

• Write in Chinese unless the user asks otherwise.
• Be concrete: name actual pages, tabs, menus, buttons, filters, fields, API endpoints, and visible states.
• Product readers should understand where to click and what to expect.
• Avoid vague bullets such as “优化样式” unless followed by exactly what changed visually or behaviorally.
• Do not invent changes not supported by git evidence.
• If a feature is present in code but hidden or disabled, explicitly say it is hidden/disabled and how product should treat it.
• Keep technical implementation details secondary and explain them only when they affect product validation.

Recommended Sections

1. Header metadata:

   • commit range
   • input mode if relevant
   • current branch
   • current HEAD
   • commit count
   • generation date

2. Date-grouped release sections:

   • 发布日期：YYYYMMDD
   • 概述
   • concrete change cards

3. 接口和数据变化

4. 产品验收地图

   • priority
   • page/module
   • required checks

5. 范围说明

   • commit range
   • whether this is start commit mode, explicit range mode, main merge mode, or main latest mode
   • whether uncommitted changes are excluded
   • verification performed

Verification

After writing the HTML, run lightweight checks:

test -s docs/acceptance/YYYY-MM-DD-system-change-acceptance.html
wc -l docs/acceptance/YYYY-MM-DD-system-change-acceptance.html
rg -n "发布日期|产品怎么验|接口和数据变化|产品验收地图|范围说明" docs/acceptance/YYYY-MM-DD-system-change-acceptance.html

Do not claim tests/build passed unless actually run. Do not start a dev server for a static HTML document unless the user asks.

Final Response

Return:

• Clickable absolute link to the generated HTML file
• The commit range used
• The input mode used
• A short note if uncommitted changes were excluded
• Verification commands actually run