session-docs-check

name	session-docs-check
description	Dùng khi user nói 'check docs', 'đã update đủ docs chưa', 'pre-merge check', 'pre-pr check', 'living docs check', '/session-docs-check', hoặc trước khi commit/push/PR/merge. Detect thay đổi trong branch hiện tại, đối chiếu với Living Documents matrix, báo cáo files PHẢI update mà chưa update (rules.md, use-cases.md, api-contract.md, ROADMAP.md, gap files, skill index, README các tầng folder).
user-invocable	true
argument-hint	[--strict] [--branch=<feature/X>] [--base=main]

/session-docs-check — Living Docs Completeness Gate

Verify mọi thay đổi trong branch đã có co-changes docs cần thiết theo CLAUDE.md §"Living Documents" + memories feedback_post_merge_doc_sync.md + feedback_wave_plan_before_serial_prs.md + rule audit-to-gap-pipeline.md Step 5.

When to use

Stage	Why
Pre-commit	Catch missing co-updates trước khi commit (cheaper than fixing after merge)
Pre-PR (gh pr create)	Last gate trước review
End of session	Verify trước khi /clear để session sau pick up trạng thái sạch
Pre-merge wave	Final gate cho wave với nhiều sub-PRs
Sau /continue	Sanity-check rằng work-in-progress không drift docs

Process

Step 1 — Detect changes in current branch

./.claude/skills/workflow/session-docs-check/scripts/check-docs.sh

Script computes:

• git diff origin/${BASE:-main} --name-only (files changed)
• git log origin/${BASE:-main}..HEAD --pretty=format:%s (commit messages)

Step 2 — Apply matrix rules

Script reads reference/doc-rules-matrix.md to map each change pattern → required co-change. Flags missing.

Step 3 — Output report

Format (Vietnamese per CLAUDE.md §CRITICAL):

## Session Docs Check (2026-04-26 17:00) — branch feature/X

✅ PASSED 8 checks
⚠️  WARN 2 checks
❌ FAILED 1 check

### Failed (PHẢI fix trước commit/PR)
- ❌ Skill `.claude/skills/quality/foo/SKILL.md` mới thêm — `_README-skills-index.md` CHƯA update
  → Fix: thêm dòng vào index

### Warnings (suggest, không block)
- ⚠️ Sửa `module/branding/handler/AIResourceHandler.java` — `documents/01-business/kitehub/ai-branding/{rules,use-cases,api-contract}.md` chưa update trong cùng branch
  → Có thể là refactor không đổi behavior (skip OK); else update docs

### Passed
- ✅ Gap file `GAP-231-...md` mới — `ROADMAP.md` đã có log entry tương ứng
- ✅ Migration `V23__...sql` thêm — `rules.md` Config Key column đã update
- ...

### Recommendation
- Strict mode (--strict): EXIT 1 nếu Failed > 0
- Default: cảnh báo + tiếp tục

Step 4 — Optional auto-fix suggestions

Cho mỗi Failed, output template diff để user copy-paste fix nhanh.

The matrix (quick reference)

Chi tiết: reference/doc-rules-matrix.md. Tóm tắt 17 rules (12 base + Rule 13 gap DONE discipline + Rule 15 wave-history append + Rule 16 wave-plan state-check + Rule 17 gap-status.csv sync + Rule 18 memory mirror PARTIAL):

#	Change pattern	Required co-update
1	**/Controller.java (new endpoint)	Domain api-contract.md
2	**/Service.java, **/Entity.java (business rule changed)	Domain rules.md + use-cases.md
3	New documents/04-quality/gaps/GAP-*.md	ROADMAP.md log entry
4	Modified GAP-*.md (status flip / log added)	ROADMAP.md log entry
5	New .claude/skills/**/SKILL.md	_README-skills-index.md entry
6	Renamed/deleted skill	All references in MEMORY.md + other skills + index
7	Modified .claude/rules/*.md	Rule's own ## Log section + version bump (per rule-change-process.md)
8	New folder under documents/	Folder README + parent README updated (per docs-folder-structure.md)
9	Migration V*.sql thêm	Domain rules.md Config Key column hoặc reference
10	application.yml key added	Domain rules.md Config Key column
11	Skill/rule meta-change	output-review-mandate.md matrix line synced (nếu liên quan)
12	Wave merge (≥3 PRs squashed within 24h)	Audit suite trigger per post-wave-audit-mandate.md §4 (3-day window)
13	Gap status flip → 🟢 DONE	AC fully checked + no banned phrases + follow-up filed (per gap-done-discipline.md)
15	Wave plan flipped to status: complete	Append valid JSON to wave-pack-planner/data/wave-history.jsonl (per wave-pack-planner SKILL.md §Rules)

Rules

• TUYỆT ĐỐI tiếng Việt trong output per CLAUDE.md §CRITICAL Communication Language
• Default mode = WARN (không exit non-zero) để không block dev workflow
• --strict mode = exit 1 nếu Failed > 0 → dùng trong CI hooks
• KHÔNG auto-fix; chỉ suggest. User own quyết định
• Script PHẢI handle clean branch (no diffs) gracefully → output "Nothing to check"
• Nếu trên main hoặc detached HEAD → cảnh báo, không chạy

Gotchas

• File renames hiện ra như delete+add → matrix rule #6 catch nếu skill renamed
• documents/03-planning/pr-logs/PR-{N}.json auto-generated by hook nhưng không auto-commit (per feedback_pr_log_commit.md) → matrix excludes from "missing doc" set
• ROADMAP.md có thể conflict khi parallel agents (per feedback_parallel_agent_strategy.md rule #2 lead-owns-shared-files) → script chỉ check existence, không check rebase-correctness
• Co-change check là PRESENCE check, không SEMANTIC check — script không hiểu nội dung doc; chỉ verify "file thuộc set required đã được modify trong branch"
• Đối với gap file edits (status flip): script check ROADMAP có entry mới nhất chứa GAP-XXX không; nếu gap chỉ change Log section nhỏ → có thể false-positive WARN
• Pre-commit hook integration: gọi với --strict trong .husky/pre-commit (Phase 2 — chưa implement; hiện tại manual invoke)

Skill contents

• SKILL.md — this file
• scripts/check-docs.sh — bash script chạy check + output report
• reference/doc-rules-matrix.md — chi tiết 12 rules + examples + edge cases

Related

• Rule CLAUDE.md §"CRITICAL: Living Documents" — primary source
• Rule .claude/rules/audit-to-gap-pipeline.md Step 5 — ROADMAP update mandatory
• Rule .claude/rules/docs-folder-structure.md — folder README requirements
• Rule .claude/rules/rule-change-process.md — rule changelog requirements
• Rule .claude/rules/post-wave-audit-mandate.md §4 — wave-merge audit cadence
• Memory feedback_post_merge_doc_sync.md — gap progress sync requirement
• Memory feedback_wave_plan_before_serial_prs.md — wave plan check (orthogonal)
• Skill .claude/skills/workflow/wave-completion-check.md — Level 7 audit suite gate (broader scope)
• Skill .claude/skills/quality/pre-flight-check.md — 3-layer check (PR/Domain/Project, broader)

Anti-patterns this skill catches

Incident	Pattern detected
2026-04-26 GAP-229 PR #562 deferred status flip	Modified gap file but status NOT flipped to DONE despite Phase 2/3 shipped
2026-04-26 PR #561 ROADMAP conflict	Both #560 and #561 added log entries — would catch if --strict ran pre-merge after rebase
Earlier waves: skill renamed without index update	New SKILL.md but _README-skills-index.md unchanged
Earlier: rule edited without §Log entry	.claude/rules/*.md modified, no ## Log line added