---
name: project-doc-governance
description: Manage project documentation as a living knowledge base for requirements, progress, architecture, quality, testing, manual acceptance, user feedback, and delivery status. Use when Codex needs to create, audit, update, or maintain project docs such as product specs, dev plans, status docs, architecture notes, test strategies, step test reports, manual acceptance cases, E2E notes, feedback logs, or release/quality records.
---

# Project Doc Governance

## Overview

Use this skill to keep project documentation operational: documents should tell the next engineer or stakeholder what the product is, where development stands, what has been tested, what changed after feedback, and what still needs attention.

## Core Rules

- Treat docs as the project's knowledge base, not as after-the-fact notes.
- Keep one source of truth for each topic; summarize and link instead of duplicating full content across files.
- Update docs whenever implementation, scope, quality status, test coverage, user feedback, or next steps change.
- Record test evidence honestly: distinguish passed, failed, skipped, blocked, partial, stopped, manual, automated, and not run.
- Keep test reports and manual acceptance cases together in the same step report unless the user explicitly asks to split them.
- Prefer tables for acceptance cases, user feedback, regression checks, quality risks, and change logs.
- Preserve the user's language and terminology. If the project docs are Chinese, write Chinese.
- Do not invent completed work, approvals, test results, commands, file paths, or dates.

## Quick Workflow

1. Inventory existing docs before changing them.
2. Identify the current development step, open feedback, quality risks, and the next acceptance target.
3. If core docs are missing, scaffold only the documents needed for the project's current maturity.
4. After implementation or fixes, update status, plan, architecture, and the relevant step test report.
5. After testing, record exactly what was run, where evidence lives, and what remains for manual acceptance.
6. After user feedback, assign feedback IDs, record the original feedback, fix summary, affected files, retest scope, and status.

## Reference Loading

- Read `references/document-set.md` when creating a documentation system, auditing what docs should exist, or deciding which file to update.
- Read `references/maintenance-workflow.md` when updating docs after implementation, tests, feedback, scope changes, or partial/failed runs.
- Read `references/templates.md` when creating new docs or normalizing messy docs into consistent sections and tables.

## Documentation Set

For a typical software project, maintain these layers:

- Project status: current progress, completed work, open issues, next step.
- Development plan: phases, order of work, deliverables, dependencies.
- Product requirements: product goals, user flows, page/module requirements, acceptance criteria.
- Architecture: code structure, data flow, key modules, design decisions.
- Test strategy: quality approach, test types, responsibilities, environments.
- Step test reports: automated checks, manual acceptance cases, user feedback, fixes, retest scope.
- E2E/automation notes when automation exists: how to run it, what it covers, what it cannot cover.
- Optional decision log or release notes when the project has repeated tradeoffs or stakeholder-facing releases.

## Update Triggers

Update docs before final response when any of these happen:

- A feature, page, API, flow, data model, UI behavior, or test script changes.
- The user accepts, rejects, or adds feedback.
- A test is run, skipped, fails, times out, or is stopped early.
- The next development step changes.
- A known issue is fixed or a new one is found.
- The implementation differs from the original plan or requirements.

## Quality Bar

- Status docs must be short enough to scan in under a minute.
- Test reports must include environment, commands or manual steps, result, evidence, remaining risks, and next manual checks.
- Manual acceptance cases must be written so a non-engineer can follow them.
- Feedback records must keep the user's wording or a faithful paraphrase, not only the implementation response.
- If a verification step was not performed, write "未执行" / "not run" and explain why.
- If an automated run timed out or was interrupted, record the last confirmed passed case and the point of failure.

## Completion Checklist

Before finishing a task that affects project knowledge:

- Relevant docs were updated or the reason for no doc update is stated.
- Step test report includes both automated evidence and manual acceptance cases when applicable.
- Current project status points to the next action.
- Known issues and residual risks are visible.
- Final answer names the updated docs and any tests that were not run.