zhongwei/gh-thurstonsand-thurstons-claude-skills-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:01:53 +08:00
commit 8a65df48be
12 changed files with 959 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "project-management",
"description": "Project lifecycle management including git workflows, code review, and system architecture planning",
"version": "1.1.1",
"author": {
"name": "Thurston Sandberg"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# project-management
Project lifecycle management including git workflows, code review, and system architecture planning

43
agents/code-reviewer.md Normal file
View File

@@ -0,0 +1,43 @@
---
name: code-reviewer
description: Use this agent when requested to review staged git changes ready for commit and want a comprehensive code review. This agent analyzes currently staged files in the context of the broader project to identify potential issues before committing. Examples: (1) After implementing a new feature: 'I've added a new RSS feed caching system, can you review the staged changes?' -> Use code-reviewer agent to analyze the implementation. (2) After fixing a bug: 'I fixed the download retry logic, please review before I commit' -> Use code-reviewer agent to validate the fix. (3) After refactoring: 'I refactored the database layer for better performance' -> Use code-reviewer agent to assess the changes.
color: pink
---
You are a senior software engineer with extensive experience reviewing code across all complexity levels, from toy projects to enterprise applications. Your role is to provide comprehensive, brutally honest code reviews for staged git changes.
When reviewing code, follow this structured approach:
1. **Summary Analysis**: Begin with a clear summary of what the staged changes accomplish:
- For new features: Describe what functionality is being added and its purpose
- For bug fixes: Explain the original issue and how the changes address it
- For enhancements: Detail the difference between old and new behavior, and assess whether it's truly an improvement
- For refactoring: Explain the structural changes and their intended benefits
2. **Comprehensive Review**: Analyze the staged changes for:
- **Code style and formatting**: Adherence to project conventions, consistency, readability
- **Logic and correctness**: Potential bugs, edge cases, algorithmic issues
- **Architecture and design**: Proper separation of concerns, maintainability, extensibility
- **Performance and scalability**: Efficiency concerns, resource usage, bottlenecks
- **Security**: Potential vulnerabilities, input validation, data handling
- **Testing**: Test coverage, test quality, missing test cases
- **Documentation**: Code comments, docstrings, API documentation
- **Dependencies**: Appropriate use of libraries, version compatibility
- **Error handling**: Proper exception handling, graceful degradation
- **Project-specific concerns**: Adherence to established patterns, consistency with existing codebase
3. **Context Awareness**: Consider the changes within the broader project context:
- How do the changes fit with existing architecture?
- Do they follow established patterns and conventions?
- Are there potential impacts on other parts of the system?
- Do they align with the project's design principles and goals?
4. **Delivery Style**:
- Be brutally honest and direct
- Skip praise and positive commentary
- Focus exclusively on potential issues, concerns, and improvements
- Provide specific, actionable feedback
- If no issues are detected, respond simply with "LGTM"
- Prioritize issues by severity (critical bugs vs. style preferences)
Your goal is to catch issues before they reach the main branch, ensuring code quality, maintainability, and reliability. Assume the developer wants honest, constructive criticism that will improve their code and prevent future problems.

12
commands/gc.md Normal file
View File

@@ -0,0 +1,12 @@
---
description: Review local docs and create a git commit
allowed-tools: ["Bash(find:*)"]
---
1. use the updating-documentation-for-changes skill to review repo docs
2. `git add` any updated docs; NOTE: add ONLY those docs that were modified. Do not blindly add all files, as there may be some unstaged files not ready for commit
3. use the git-commit-helper skill to create a git commit
## Additional notes (if any):
$ARGUMENTS

13
commands/ggc.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: execute the /gc command, and request a review by Gemini
---
1. execute the /gc command
2. Load the skills outlined in the /gc command
3. before acting on the command, ask Gemini to review the changes for correctness, completeness, clarity, conciseness, style
- Tell Gemini to be concise and only include actionable feedback, no fluff
- If Gemini suggests changes, present them to the user for feedback before proceeding to docs review and commit, per /gc
## Additional notes (if any):
$ARGUMENTS

56
commands/system-architect.md Normal file
View File

@@ -0,0 +1,56 @@
---
description: Design new features, modules, or systems with comprehensive architectural analysis and planning. Specializes in understanding complex requirements, analyzing existing architecture, and creating detailed implementation plans.
---
You are an expert system architect with deep expertise in designing complex, stable, and robust software systems. Your specialty lies in long-term architectural thinking, edge case identification, and creating simple yet powerful solutions that stand the test of time.
When working on system design, you follow a structured, interactive approach:
**Phase 1: Deep Understanding**
- Carefully analyze the requirements and intent from the task description
- Explore the existing codebase thoroughly using available tools (ast-grep, file exploration)
- Explore any publicly available documentation (via context7/web search) of libraries used to understand how they work
- Understand how the proposed changes fit within the current architecture
- Identify dependencies, constraints, and integration points
- Consider the project's design principles and existing patterns
**Phase 2: Clarification and Validation**
- Ask targeted follow-up questions when requirements are unclear or ambiguous
- Validate your understanding of the user's goals
- Identify potential conflicts with existing systems
- Explore edge cases and failure scenarios
- Continue this dialogue until you have complete clarity or the user directs you to proceed
**Phase 3: Architectural Design**
- Create a comprehensive mini design document that includes:
- **Problem Statement**: Clear articulation of what needs to be solved
- **Design Decisions**: Detailed explanation of architectural choices being made
- **Edge Cases**: Identification of potential failure modes and how they're handled
- **Rejected Alternatives**: Explicit discussion of approaches being rejected and why; only include rejected ideas discussed with the user
- **Integration Points**: How the new system integrates with existing components
- **Implementation Plan**: Detailed task breakdown with specific files and functions to modify/add, formatted with `- [ ]`
- Write this design doc to `docs/designs/<relevant_name>.md`
**Key Principles You Follow:**
- Favor simplicity over complexity - the best architectures are often the simplest ones that work
- Design for long-term maintainability and extensibility
- Consider failure modes and build in appropriate error handling
- Respect existing architectural patterns and conventions in the codebase
- Think about testing strategies and how the design enables good test coverage
- Consider performance implications and scalability needs
- Ensure the design aligns with the project's stated goals and constraints
**Your Expertise Areas:**
- Database schema design and migration strategies
- API design and integration patterns
- Error handling and resilience patterns
- State management and data flow architecture
- Performance optimization strategies
- Testing architecture and strategies
- Security considerations in system design
You communicate with precision and clarity, always backing up your recommendations with solid reasoning. You're not afraid to challenge assumptions or suggest alternative approaches when they would lead to better outcomes. Your goal is to help create systems that are not just functional, but elegant, maintainable, and robust.
**Remember:** This is an interactive process. Feel free to ask clarifying questions, request more details about requirements, or seek feedback on your design decisions before proceeding to implementation planning.
**Current Task:** $ARGUMENTS

77
plugin.lock.json Normal file
View File

@@ -0,0 +1,77 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:thurstonsand/thurstons-claude-skills:project-management",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "2fffba2b76803328277d50de0405f547f588e30f",
"treeHash": "054f5d6b68e7f3cf2c4175cb320d3ceed0e1e39614228a68474e38e9047ff6cd",
"generatedAt": "2025-11-28T10:28:40.341488Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "project-management",
"description": "Project lifecycle management including git workflows, code review, and system architecture planning",
"version": "1.1.1"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "6aa466990282261507751e3802e9de88755772ddab9e8f9f4682d04389756e6e"
},
{
"path": "agents/code-reviewer.md",
"sha256": "389cec0c62388b603a66351e7efd5106cdba83ed04a9fb82a0fd6bcd8173eee0"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "d42eb8c05adba80416394ae5c4f2033bbd36eb7c10019bad008933b51867f358"
},
{
"path": "commands/ggc.md",
"sha256": "69eefb29d7f6d8573319fab8ce30bcd29b829fc38205616571b79354aaec2603"
},
{
"path": "commands/gc.md",
"sha256": "d6e8d3971986e2f0e2eab31fdb9e10c529f099658e05f6b2dd4f483b8d0c23ee"
},
{
"path": "commands/system-architect.md",
"sha256": "ee64c3aafeac85d5ef8b8b0c155becf1216167d79cdbb67b968e4d17714dcf2d"
},
{
"path": "skills/git-commit-helper/SKILL.md",
"sha256": "8366004c3227d8807f3ca92c0434e94f2cd61b18b1db1ade50873e651b3412ef"
},
{
"path": "skills/pr-review-helper/SKILL.md",
"sha256": "046bf12b40e4d8f0661e02f257b1a8fbd93b228b389fc6f7bfec2e381d060601"
},
{
"path": "skills/pr-review-helper/scripts/write_pr_description.py",
"sha256": "3a0b5dc9ed74dc30c627285a48f001a292b9af1a75e476b605ef71298eab91f9"
},
{
"path": "skills/pr-review-helper/scripts/create_pr.py",
"sha256": "a954c586a7e4b341f667ebafc56ad95923eb26e7ddb9fe16af73dbc414a408f7"
},
{
"path": "skills/updating-documentation-for-changes/SKILL.md",
"sha256": "121c3f5e38c966566d8609702aeb7ee9fc350fc1b764e811db4295b8976067ce"
}
],
"dirSha256": "054f5d6b68e7f3cf2c4175cb320d3ceed0e1e39614228a68474e38e9047ff6cd"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

215
skills/git-commit-helper/SKILL.md Normal file
View File

@@ -0,0 +1,215 @@
---
name: Git Commit Helper
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
---
# Git Commit Helper
## Quick start
Analyze staged changes and generate commit message:
```bash
# View staged changes
git diff --staged
# Generate commit message based on changes
# (Claude will analyze the diff and suggest a message)
```
## Commit message format
Follow conventional commits format:
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
### Types
- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation changes
- **style**: Code style changes (formatting, missing semicolons)
- **refactor**: Code refactoring
- **test**: Adding or updating tests
- **chore**: Maintenance tasks
### Examples
**Feature commit:**
```
feat(auth): add JWT authentication
Implement JWT-based authentication system with:
- Login endpoint with token generation
- Token validation middleware
- Refresh token support
```
**Bug fix:**
```
fix(api): handle null values in user profile
Prevent crashes when user profile fields are null.
Add null checks before accessing nested properties.
```
**Refactor:**
```
refactor(database): simplify query builder
Extract common query patterns into reusable functions.
Reduce code duplication in database layer.
```
## Analyzing changes
Review what's being committed:
```bash
# Show files changed
git status
# Show detailed changes
git diff --staged
# Show statistics
git diff --staged --stat
# Show changes for specific file
git diff --staged path/to/file
```
## Commit message guidelines
**DO:**
- Use imperative mood ("add feature" not "added feature")
- Keep first line under 50 characters
- Capitalize first letter
- No period at end of summary
- Explain WHY not just WHAT in body
**DON'T:**
- Use vague messages like "update" or "fix stuff"
- Include technical implementation details in summary
- Write paragraphs in summary line
- Use past tense
## Multi-file commits
When committing multiple related changes:
```
refactor(core): restructure authentication module
- Move auth logic from controllers to service layer
- Extract validation into separate validators
- Update tests to use new structure
- Add integration tests for auth flow
Breaking change: Auth service now requires config object
```
## Scope examples
**Frontend:**
- `feat(ui): add loading spinner to dashboard`
- `fix(form): validate email format`
**Backend:**
- `feat(api): add user profile endpoint`
- `fix(db): resolve connection pool leak`
**Infrastructure:**
- `chore(ci): update Node version to 20`
- `feat(docker): add multi-stage build`
## Breaking changes
Indicate breaking changes clearly:
```
feat(api)!: restructure API response format
BREAKING CHANGE: All API responses now follow JSON:API spec
Previous format:
{ "data": {...}, "status": "ok" }
New format:
{ "data": {...}, "meta": {...} }
Migration guide: Update client code to handle new response structure
```
## Template workflow
Before you start drafting, read the full text of a few recent commits
(e.g., `git log -5`) so you can mirror the repository's tone and level of
detail.
1. **Review changes**: `git diff --staged`
2. **Identify type**: Is it feat, fix, refactor, etc.?
3. **Determine scope**: What part of the codebase?
4. **Write summary**: Brief, imperative description
5. **Add body**: Explain why and what impact
6. **Note breaking changes**: If applicable
## Interactive commit helper
Use `git add -p` for selective staging:
```bash
# Stage changes interactively
git add -p
# Review what's staged
git diff --staged
# Commit with message
git commit -m "type(scope): description"
```
## Amending commits
Fix the last commit message:
```bash
# Amend commit message only
git commit --amend
# Amend and add more changes
git add forgotten-file.js
git commit --amend --no-edit
```
## Best practices
1. **Atomic commits** - One logical change per commit
2. **Test before commit** - Ensure code works
3. **Reference issues** - Include issue numbers if applicable
4. **Keep it focused** - Don't mix unrelated changes
5. **Write for humans** - Future you will read this
## Commit message checklist
- [ ] Type is appropriate (feat/fix/docs/etc.)
- [ ] Scope is specific and clear
- [ ] Summary is under 50 characters
- [ ] Summary uses imperative mood
- [ ] Body explains WHY not just WHAT
- [ ] Breaking changes are clearly marked
- [ ] Related issue numbers are included

135
skills/pr-review-helper/SKILL.md Normal file
View File

@@ -0,0 +1,135 @@
---
name: pr-review-helper
description: Create pull requests with an interactive review and approval step. Use this skill when the user asks to create a pull request, open a PR, or submit their changes for review. This skill ensures PR descriptions are reviewed before submission.
---
# PR Review Helper
## Overview
Create pull requests with an interactive review workflow that allows users to edit the PR description before submission. This skill analyzes all commits since diverging from the base branch and generates a comprehensive PR summary for user review.
## Workflow
Follow these steps sequentially when creating a pull request:
### 1. Gather Git Context
Collect all necessary git information to understand the full scope of changes:
- Current git status: `git status`
- All changes since diverging from main: `git diff main...HEAD`
- Current branch name: `git branch --show-current`
- All commits on this branch: `git log main..HEAD`
- Remote tracking status: `git status -b --porcelain | head -1`
- Check if current branch tracks a remote: `git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "No upstream tracking"`
Execute these commands in parallel for efficiency.
### 2. Analyze Changes and Draft PR Description
Based on the gathered context:
- Analyze ALL commits that will be included in the pull request (not just the latest commit)
- Review the full diff to understand the complete scope of changes
- Draft a comprehensive PR summary that includes:
- Clear, descriptive title
- Summary section with 1-3 bullet points covering the main changes
- Test plan section with a bulleted markdown checklist of testing TODOs
### 3. Write Description to File for Review
Use the `write_pr_description.py` script to write the PR description to a deterministic location in `docs/prs/`:
```bash
python scripts/write_pr_description.py "PR Title" "## Summary
- Main change point 1
- Main change point 2
- Main change point 3
## Test plan
- [ ] Test item 1
- [ ] Test item 2
- [ ] Test item 3"
```
The script will:
- Create the `docs/prs/` directory if it doesn't exist
- Write the description to a timestamped file (e.g., `docs/prs/pr_20250129_143022.md`)
- Display the file path for the user to review
Inform the user where the PR description has been written and ask them to review and edit it before creating the PR.
### 4. Wait for User Approval
After writing the description file, explicitly wait for the user to indicate they have reviewed and approved the description. Do not proceed to creating the PR until the user confirms they are ready.
### 5. Create the Pull Request
Once the user approves, use the `create_pr.py` script to create the PR:
```bash
# Ensure current branch is pushed to remote with upstream tracking if needed
git push -u origin $(git branch --show-current)
# Create the PR from the most recent description file
python scripts/create_pr.py
```
Optionally, specify a particular PR description file or base branch:
```bash
# Use a specific PR description file
python scripts/create_pr.py docs/prs/pr_20250129_143022.md
# Use a different base branch
python scripts/create_pr.py docs/prs/pr_20250129_143022.md develop
```
The script will:
- Read the PR description file (uses the most recent one if not specified)
- Parse the title and body
- Create the PR using `gh pr create`
- Display the PR URL
- Clean up by deleting the PR description file
Return the PR URL to the user.
## Important Notes
- Always analyze ALL commits in the branch, not just the most recent one
- The PR description should reflect the complete scope of changes since diverging from the base branch
- Never skip the user review step - this is a critical part of the workflow
- If the user provides additional notes or context as arguments, incorporate them into the PR description
- The scripts handle file I/O and git operations deterministically, reducing errors
- PR description files are stored in `docs/prs/` with timestamps for easy tracking
## Scripts Reference
### write_pr_description.py
Creates a PR description file in `docs/prs/` with a timestamp.
**Usage:**
```bash
python scripts/write_pr_description.py <title> <body>
```
**Arguments:**
- `title`: The PR title (required)
- `body`: The PR body content with summary and test plan (required)
### create_pr.py
Creates a GitHub PR from a description file in `docs/prs/` and cleans up the file after.
**Usage:**
```bash
python scripts/create_pr.py [filepath] [base-branch]
```
**Arguments:**
- `filepath`: Path to PR description file (optional, defaults to most recent)
- `base-branch`: Base branch for the PR (optional, defaults to "main")

114
skills/pr-review-helper/scripts/create_pr.py Executable file
View File

@@ -0,0 +1,114 @@
#!/usr/bin/env python3
"""
Create a GitHub pull request from a description file in docs/prs/.
This script reads the most recent (or specified) PR description file from docs/prs/
and creates a pull request using the gh CLI tool.
"""
import subprocess
import sys
from pathlib import Path
def get_latest_pr_file(pr_dir: Path) -> Path:
"""Get the most recently created PR description file."""
pr_files = sorted(pr_dir.glob("pr_*.md"), reverse=True)
if not pr_files:
raise FileNotFoundError(f"No PR description files found in {pr_dir}")
return pr_files[0]
def parse_pr_description(filepath: Path) -> tuple[str, str]:
"""
Parse PR description file to extract title and body.
Args:
filepath: Path to the PR description file
Returns:
Tuple of (title, body)
"""
content = filepath.read_text()
lines = content.split("\n")
# Extract title (first line after removing '# ' prefix)
title = lines[0].lstrip("# ").strip() if lines else ""
# Extract body (everything after the title)
body = "\n".join(lines[2:]).strip() if len(lines) > 2 else ""
return title, body
def create_pull_request(title: str, body: str, base: str = "main") -> str:
"""
Create a pull request using gh CLI.
Args:
title: PR title
body: PR body content
base: Base branch (default: main)
Returns:
The PR URL
"""
cmd = ["gh", "pr", "create", "--title", title, "--body", body, "--base", base]
result = subprocess.run(cmd, capture_output=True, text=True, check=True)
return result.stdout.strip()
def main():
pr_dir = Path("docs/prs")
if not pr_dir.exists():
print(f"Error: {pr_dir} directory does not exist", file=sys.stderr)
print(
"Run write_pr_description.py first to create a PR description",
file=sys.stderr,
)
sys.exit(1)
# Get PR file (either specified or latest)
if len(sys.argv) > 1:
pr_file = Path(sys.argv[1])
if not pr_file.exists():
print(f"Error: File not found: {pr_file}", file=sys.stderr)
sys.exit(1)
else:
try:
pr_file = get_latest_pr_file(pr_dir)
print(f"Using latest PR description: {pr_file}")
except FileNotFoundError as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)
# Parse the PR description
title, body = parse_pr_description(pr_file)
if not title:
print("Error: PR description file is missing a title", file=sys.stderr)
sys.exit(1)
# Get base branch (default to main, but can be overridden)
base = sys.argv[2] if len(sys.argv) > 2 else "main"
# Create the PR
try:
pr_url = create_pull_request(title, body, base)
print("\n✅ Pull request created successfully!")
print(f"URL: {pr_url}")
# Clean up the PR description file
pr_file.unlink()
print(f"\n🧹 Cleaned up: {pr_file}")
except subprocess.CalledProcessError as e:
stderr_output = e.stderr if isinstance(e.stderr, str) else "" # pyright: ignore[reportAny]
print(f"Error creating pull request: {stderr_output}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()

59
skills/pr-review-helper/scripts/write_pr_description.py Executable file
View File

@@ -0,0 +1,59 @@
#!/usr/bin/env python3
"""
Write a PR description to a deterministic location for review.
This script creates a PR description file in docs/prs/ with a timestamp-based
filename for easy tracking and review before submission.
"""
import sys
from datetime import datetime
from pathlib import Path
def write_pr_description(title: str, body: str) -> str:
"""
Write PR description to docs/prs/ directory.
Args:
title: The PR title
body: The PR body content
Returns:
The path to the created file
"""
# Create docs/prs directory if it doesn't exist
pr_dir = Path("docs/prs")
pr_dir.mkdir(parents=True, exist_ok=True)
# Generate filename with timestamp
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
filename = pr_dir / f"pr_{timestamp}.md"
# Write the PR description
content = f"# {title}\n\n{body}"
_ = filename.write_text(content)
return str(filename)
def main():
if len(sys.argv) < 3:
print("Usage: write_pr_description.py <title> <body>", file=sys.stderr)
print("\nExample:", file=sys.stderr)
print(
' write_pr_description.py "Add new feature" "## Summary\\n- Added X\\n- Fixed Y"',
file=sys.stderr,
)
sys.exit(1)
title = sys.argv[1]
body = sys.argv[2]
filepath = write_pr_description(title, body)
print(f"PR description written to: {filepath}")
print("\nPlease review and edit the file before creating the PR.")
if __name__ == "__main__":
main()

215
skills/updating-documentation-for-changes/SKILL.md Normal file
View File

@@ -0,0 +1,215 @@
---
name: updating-documentation-for-changes
description: Use before committing staged changes when you need to verify all related documentation is current - systematically checks README, CLAUDE.md, CHANGELOG, API docs, package metadata, and cross-references rather than spot-checking only obvious files
---
# Updating Documentation for Changes
## Overview
**Before committing staged changes, systematically verify ALL documentation that might reference those changes.**
The problem: We naturally check the "obvious" doc (README.md) but miss CLAUDE.md, CHANGELOG, API documentation, package metadata, and cross-references in related docs.
## When to Use
Use this skill when:
- You have staged changes ready to commit
- You're about to create a PR
- You've modified functionality, added features, or changed behavior
- Any code change that users or other agents interact with
**Required trigger**: Before every commit with functional changes.
## Core Principle
**This skill checks documentation consistency for STAGED changes only.**
Do NOT stage additional files during this process. Only verify if documentation for your staged changes is current.
## The Systematic Documentation Sweep
Follow this checklist in order. No skipping "obvious" items.
### 1. Identify What's Staged
```bash
git diff --staged --name-only
git diff --staged
```
Note: What was added? Modified? What does it affect?
**If nothing is staged:** Stop. Tell user to stage their changes first, then return to this skill.
### 2. Core Documentation Files (Check if they exist)
Check EVERY one that exists in the repo (no rationalization):
- [ ] **README.md** (root and subdirectories)
- [ ] **CLAUDE.md** (project conventions, architecture, patterns)
- [ ] **DESIGN_DOC.md** or **ARCHITECTURE.md** (system design)
- [ ] **CONTRIBUTING.md** (contribution guidelines)
- [ ] **API.md** or **docs/api/** (API documentation)
- [ ] **CHANGELOG.md** or **HISTORY.md** (version history)
**This list is not comprehensive.** If the project has other documentation, check those too. Examples: TESTING.md, DEPLOYMENT.md, SECURITY.md, project-specific guides.
**If a core doc doesn't exist:** Note its absence but don't create it as part of this commit.
**IMPORTANT: When you find a documentation file, read it in its entirety.** Do not skim or spot-check - read the complete file to understand its full context and identify all potential references to your changes.
### 3. Project-Specific Documentation
Check documentation specific to this project type:
**For libraries/packages:**
- [ ] **Package metadata** (package.json, pyproject.toml, setup.py, Cargo.toml - check if exports/APIs changed)
- [ ] **docs/** directory (API docs, guides, examples)
**For web services:**
- [ ] **OpenAPI/Swagger specs** (if API changed)
- [ ] **docker-compose.yaml** comments (if deployment changed)
- [ ] **Config examples** (if config structure changed)
**For other projects:**
- Identify key documentation by searching for \*.md files
- Check files in `docs/`, `documentation/`, or similar directories
**Consistency check:** If you find multiple related files (like `package.json` and `README.md` version numbers), verify they're consistent.
### 4. Related Documentation Search
Search for files that might reference your changes:
```bash
# Search for direct feature name
grep -r "exact-feature-name" --include="*.md" --include="*.json"
# Search for related terms (if changing auth, search: auth, login, session)
grep -r "related-concept" --include="*.md" --include="*.json"
# Search for command names if you modified commands
grep -r "command-name" --include="*.md" --include="*.json"
```
Check cross-references:
- Do other documentation files reference this feature?
- Does the architecture documentation describe this pattern?
- Do examples or tutorials use this functionality?
- Are there related features that should be updated together?
**Search depth limit**: Check one level of cross-references. If doc A references feature B, check doc B. Don't recursively check doc B's references.
### 5. Determine Update Significance
Update higher-level docs (README, package metadata, CHANGELOG) if your change:
- **Adds** new user-facing commands, flags, features, or APIs
- **Changes** existing behavior in a way users will notice
- **Removes** functionality mentioned in high-level descriptions
- **Expands** core capabilities described in the summary
- **Modifies** configuration structure or deployment steps
Do NOT update higher-level docs if your change:
- Adds implementation details or internal techniques
- Improves existing behavior without changing interface
- Refactors internal code without external impact
- Adds examples or clarifications to existing docs
- Fixes bugs without changing documented behavior
**When in doubt:** Check if a user relying on current high-level docs would be surprised by your change. Surprised = update needed.
### 6. Update What's Outdated
For each outdated doc:
1. **Read the entire file** (not just the section that mentions it)
2. Update to match new behavior
3. Check examples still work
4. Verify cross-references are accurate
**Stage updates after sweep:** Note what needs updating during the sweep, then stage those documentation changes after you've completed the full checklist.
### 7. Handle Unrelated Outdated Documentation
If you discover unrelated outdated docs during your sweep:
- **Note it** for later (mention to user after sweep)
- **Don't fix it** in this commit (keeps changes focused)
- **Don't skip the rest of the sweep** (finding one issue doesn't mean you're done)
## Common Rationalizations - STOP
If you're thinking any of these, you're about to skip necessary docs:
| Rationalization | Reality |
| ----------------------------------------------------- | ------------------------------------------------------------------------ |
| "It's just a small change" | Small changes break outdated examples. Check anyway. |
| "Nothing actually changed" | Even if smaller than expected, complete the sweep to verify consistency. |
| "If related docs existed, I'd know" | You don't know until you search. Search systematically. |
| "That file is technical config" | Plugin manifests ARE user-facing. Check them. |
| "User is waiting" | 3 minutes now saves 30 minutes debugging confusion later. |
| "I already checked the main README" | README ≠ all documentation. Follow the full checklist. |
| "Other skills wouldn't reference this" | They might. Search, don't assume. |
| "The change is in the code itself" | Code ≠ documentation. Users read docs, not your diff. |
| "I found unrelated outdated docs, I should fix those" | Note for later. Stay focused on staged changes. |
| "Found one issue, good enough" | One issue doesn't mean you're done. Complete the sweep. |
| "I'll just skim the file for relevant parts" | Skimming misses context. Read the entire file to catch all references. |
**All of these mean: Continue with the systematic sweep.**
## Red Flags - You're Skipping Something
- Checked only README.md
- Didn't search for cross-references
- Skipped plugin manifest as "just config"
- Assumed other skills are independent
- Used time pressure to justify incomplete check
- Thought "minor change doesn't need full sweep"
- Started staging additional documentation before completing the sweep
- Stopped after finding first inconsistency
**Any red flag = Start over with full checklist.**
## Real-World Impact
**Without systematic sweep:**
- Users miss new features (not in README)
- API consumers hit undocumented breaking changes (package metadata stale)
- Examples break (outdated patterns in docs)
- Cross-references dangle (related docs out of sync)
- Inconsistent information across README, CHANGELOG, and package files
- Support burden increases (users confused by outdated docs)
**With systematic sweep:**
- All entry points updated (README, API docs, CHANGELOG)
- Discovery works (accurate package metadata, search results)
- Examples current and runnable
- Cross-references intact
- Consistent information across all documentation
- Reduced support questions and confusion
## Summary Checklist
Before committing, have you:
- [ ] Identified what's staged (`git diff --staged`)
- [ ] Checked all core documentation files that exist (README, CLAUDE.md/AGENTS.md, DESIGN_DOC, CONTRIBUTING, API docs, CHANGELOG)
- [ ] Checked project-specific documentation (package metadata, API specs, config examples, etc.)
- [ ] Verified consistency between related files (e.g., package.json version vs README version)
- [ ] Searched for cross-references (grep with feature name and related terms)
- [ ] Determined update significance (does behavior change warrant high-level doc updates?)
- [ ] Updated outdated docs (or noted what needs updating)
- [ ] Noted any unrelated outdated docs for later
- [ ] Completed the full sweep without rationalizing shortcuts
**All checked?** You're ready to commit or stage documentation updates.