03-documentation

name	03-documentation
description	Project Documentation Manager. Handles the lifecycle of feature specifications, from PRD completion to archival, test logging, and maintenance records. Use this skill when a feature implementation is complete, when testing results need to be logged, or when a bug fix/optimization needs to be recorded in the feature history.

Project Documentation Manager

Overview

This skill acts as the "Librarian" and "Historian" for the project. It bridges the gap between the planning phase (PRDs) and the engineering phase (Code, Tests, Maintenance). Its primary responsibility is to maintain the "Source of Truth" for what has been implemented in the project.

Why this is critical: Code rots. Tests fail. But a well-maintained Specification Log ensures we always know what was built, why it was built, and how it has changed over time.

Language Requirement (语言要求)

All generated documentation MUST be in Simplified Chinese (简体中文).

• Callers (Skills 04-08): When providing descriptions (--desc, --details), you MUST translate them to Chinese if your internal reasoning was in English.
• Scripts: The scripts in this skill have been localized to output Chinese headers and labels.

Documentation Management Standards (文档管理规范)

1. Requirement & Change Management (需求与变更管理)

• Centralized Modification: All modifications for the same Product Requirement Document (PRD) must be centrally maintained.
• Structured Archiving: In the specs directory, a dedicated folder MUST be created for each modified PRD. This folder name should match the requirement document structure (e.g., matching f:\AIGC\AIYskills\.wisdom\project\requirement).
• Traceability: This folder is used to archive all change records, design decisions, and interface updates related to that PRD, ensuring synchronization with f:\AIGC\AIYskills\.wisdom\project\changes.

2. Tech Stack & Project Standards Synchronization (技术栈与项目规范同步)

• Tech Stack: If a development task introduces a new tech stack, framework, library, or tool, its detailed description, version information, and reason for introduction MUST be updated in f:\AIGC\AIYskills\.wisdom\project\architecture.md.
• Principles: If a development task follows or establishes new project-specific standards, coding guidelines, directory structure conventions, or best practices, they MUST be clearly defined and updated in f:\AIGC\AIYskills\.wisdom\project\principles.md.

3. Project Overview Maintenance (项目总览文档维护)

• Continuous Updates: Based on the archived content in specs, the evolution of the project architecture, and the tech stack used, the project overview document f:\AIGC\AIYskills\.wisdom\project\AGENTS.md MUST be continuously maintained.
• Accuracy: Ensure AGENTS.md accurately reflects the project's core information, including introduction, architecture diagrams, tech stack lists, core module descriptions, development/deployment guides, and Agent responsibilities/workflows.

Caller Responsibility Matrix

This table defines exactly which documents are maintained when this skill is called by other specialists.

Caller Skill	Action Type	Primary Target File (Updated)	Secondary Index (Updated)	Status Change
04-coding-standards	Archive Feature	.wisdom/project/specs/<Project>/<Feature>.md (Creates New in Subfolder)	specs/implemented-features.md	PRD -> Completed
05-testing	Log Test Result	.wisdom/project/specs/<Project>/<Feature>.md (Appends to Test History)	-	Spec -> Verified/Failed
06-bug-fixing	Log Bug Fix	.wisdom/project/specs/<Project>/<Feature>.md (Appends to Changelog)	-	-
07-optimization	Log Optimization	.wisdom/project/specs/<Project>/<Feature>.md (Appends to Changelog)	-	-
08-security	Log Security Patch	.wisdom/project/specs/<Project>/<Feature>.md (Appends to Changelog)	-	-

Workflows

1. Archiving a Feature (Called by 04-coding-standards)

Context: A developer has finished implementing a feature or an enhancement. Goal: Convert the "Plan" (PRD) into a "Record" (Spec), or update an existing record.

Action:

• New Feature: Creates a new Specification file in .wisdom/project/specs/<ProjectName>/.
• Enhancement/Fix: Appends to the ## Changelog of an existing Spec file using --update.

Usage (New Feature):

python .wisdom/skills/03-documentation/scripts/archive_feature.py --project <ProjectName> --feature <FeatureName> --desc "<Brief Description>"

Usage (Enhancement/Update):

python .wisdom/skills/03-documentation/scripts/archive_feature.py --project <ProjectName> --update <MainSpecName> --desc "<Change Description>"

Note: Do not create separate MD files for small UI tweaks or minor logic changes. Merge them into the main feature spec.

Examples:

• ✅ New: --feature LoginSystem --desc "Implemented full login flow"
• ✅ Update: --update LoginSystem --desc "Added 'Forgot Password' link to login form"
• ❌ Bad: Creating LoginForgotPassword.md for a small button addition.

2. Logging Test Results (Called by 05-testing)

Context: QA has run a test suite (Pass or Fail). Goal: Record the verification status of the feature.

Action:

1. Updates: The specific Feature Spec file (.wisdom/project/specs/<Project>/<Feature>.md).
2. Appends: A new entry under the ## Test History section.

Usage:

python .wisdom/skills/03-documentation/scripts/log_test_result.py --spec <Project>/<SpecFileName> --status <Pass|Fail> --details "<Test Summary (Chinese)>"

3. Logging Maintenance (Called by 06, 07, 08)

Context: A bug was fixed, code was optimized, or a security patch was applied. Goal: Maintain a history of why the code changed after initial implementation.

Action:

1. Updates: The specific Feature Spec file (.wisdom/project/specs/<Project>/<Feature>.md).
2. Appends: A new entry under the ## Changelog section with the appropriate type icon (🐛, ⚡, 🛡️).

Usage:

python .wisdom/skills/03-documentation/scripts/log_maintenance.py --spec <Project>/<SpecFileName> --type <BugFix|Optimization|Security> --desc "<Change Description (Chinese)>"

Directory Structure

• Scripts:
  • archive_feature.py: Main logic for PRD -> Spec transition. Supports project subdirectories.
  • log_test_result.py: Appends test outcomes.
  • log_maintenance.py: Appends maintenance logs.
  • validate_specs.py: Checks integrity of spec files.

Best Practices

• Atomic Updates: Always log changes immediately after they happen.
• Traceability: Ensure every log entry points back to a specific requirement or issue if possible.
• Single Source of Truth: The files in .wisdom/project/specs/ are the definitive record of what the software actually does (vs. what the PRD said it should do).
• Keep Meta-Docs Fresh: architecture.md and AGENTS.md should never lag behind the actual code. Update them immediately after a major feature or tech stack change.