# Product Acceptance Doc

> Generate a product-facing HTML change document or acceptance document from a git commitId range. Use when the user provides a commitId and asks for a product document, release notes, change summary, acceptance checklist, or a directly openable HTML file for product QA.

- Skill: `sonia420116xh-max/product-acceptance-doc` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add sonia420116xh-max/product-acceptance-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sonia420116xh-max/product-acceptance-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: sonia420116xh-max (https://skillmd.com/u/sonia420116xh-max)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/sonia420116xh-max/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:

```text
<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:

```text
$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:

```text
$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:

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

Interpret the range as:

```text
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:

```bash
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:

```text
$product-acceptance-doc main-latest
```

Resolve the latest two first-parent commits on `main`:

```bash
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:

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

Interpret the range as:

```text
<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:

   ```bash
   git cat-file -t <commit>
   ```

3. Gather source evidence before writing:

   ```bash
   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:

```text
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:

```bash
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