Merge pull request #15 from thxtech/feat/update-docs-skill

feat: add update-docs skill for syncing supplementary documents

Author: thxtech

.claude/skills/analyze-oss/SKILL.md

@@ -89,9 +89,7 @@ After writing the report, update the following documents to keep them in sync:
 
 1. docs/ROADMAP.md: Add the new project to the appropriate difficulty level (Beginner / Intermediate / Advanced) based on architectural complexity. Also check if it fits any existing Learning Paths or warrants a new one.
 
-2. docs/COMPARISONS.md: Check if the new project is similar to any existing comparison group (e.g., a new database should be considered for the Key-Value Stores or Database sections). If a good comparison exists, add a new section or extend an existing one.
-
-3. docs/PATTERNS.md: Check if the new project uses any design patterns already documented (Plugin Architecture, WAL, Raft, Pipeline, etc.). Add the project to the relevant pattern tables with a brief description of its implementation.
+2. docs/PATTERNS.md: Check if the new project uses any design patterns already documented (Plugin Architecture, WAL, Raft, Pipeline, etc.). Add the project to the relevant pattern tables with a brief description of its implementation.
 
 Run `bash scripts/audit-docs.sh` to verify consistency after updates.
 

.claude/skills/update-docs/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: update-docs
+description: Update all supplementary documents (TABLE, ROADMAP, PATTERNS) to reflect the current state of oss/ reports. Use when the user asks to update, refresh, or sync documentation.
+allowed-tools: Bash(bash:*), Read, Write, Edit, Glob, Grep
+---
+
+# Documentation Updater
+
+Bring all supplementary documents in `docs/` up to date with the current `oss/` reports.
+
+## Step 1: Run the audit
+
+Run `bash scripts/audit-docs.sh` to identify gaps between `oss/` reports and documentation.
+
+Save the output for reference throughout the remaining steps.
+
+## Step 2: Regenerate TABLE.md
+
+Run `bash scripts/generate-table.sh` to rebuild `docs/TABLE.md` from scratch. This is fully automated and always produces the correct result.
+
+## Step 3: Update ROADMAP.md
+
+Read `docs/ROADMAP.md` and identify projects missing from it (listed in the audit output).
+
+For each missing project:
+1. Read its `oss/{project}/README.md` to understand its architectural complexity
+2. Determine difficulty level:
+   - Beginner: focused scope, clean codebase, straightforward architecture, single-purpose
+   - Intermediate: multiple subsystems, distributed components, sophisticated data structures
+   - Advanced: massive-scale distributed systems, novel algorithms, complex consensus/scheduling
+3. Add a row to the appropriate difficulty table: `| [{name}](../oss/{project}/README.md) | {why} |`
+4. Check if the project fits any existing Learning Path. If so, add it there too.
+
+Follow the existing writing style. Keep "Why Start Here" / "What You'll Learn" descriptions to one concise sentence.
+
+## Step 4: Update PATTERNS.md
+
+Read `docs/PATTERNS.md` to understand the documented patterns.
+
+For each project NOT yet referenced in PATTERNS.md:
+1. Read its `oss/{project}/README.md`, especially Core Components and Key Design Decisions
+2. Identify which documented patterns the project uses (Plugin Architecture, Pipeline, Event-Driven, WAL, LSM-Tree, Raft, MVCC, Middleware, Work-Stealing, Declarative Reconciliation, Actor Model, Distributed Snapshots, Content-Addressable Storage)
+3. Add a row to each matching pattern table: `| [{name}](../oss/{project}/README.md) | {implementation details} |`
+4. If the project uses a pattern not yet documented and at least 3 projects share it, create a new pattern section
+
+Keep implementation details concise (2-3 sentences) and specific to the project. Reference actual module names, interfaces, or techniques.
+
+## Step 5: Verify
+
+Run `bash scripts/audit-docs.sh` again and confirm:
+- TABLE.md: 0 errors
+- ROADMAP.md: 0 warnings (all projects covered)
+- PATTERNS.md: coverage improved
+
+## Rules
+
+- Write entirely in English
+- Do NOT use markdown bold syntax (`**`) anywhere
+- Follow the existing format and writing style of each document
+- Use relative links: `../oss/{project}/README.md`
+- Do not add projects that do not exist under `oss/`
+- Prioritize accuracy over coverage. If unsure about a project's patterns or difficulty, read its report first

.github/workflows/audit-docs.yml

@@ -38,7 +38,7 @@ jobs:
         with:
           script: |
             const output = process.env.AUDIT_OUTPUT;
-            const body = `## Documentation Audit Report\n\n\`\`\`\n${output}\n\`\`\`\n\nPlease update the supplementary documents (docs/ROADMAP.md, docs/COMPARISONS.md, docs/PATTERNS.md) for new projects.\n\nRun \`bash scripts/audit-docs.sh\` locally to check.`;
+            const body = `## Documentation Audit Report\n\n\`\`\`\n${output}\n\`\`\`\n\nPlease update the supplementary documents (docs/ROADMAP.md, docs/PATTERNS.md) for new projects.\n\nRun \`bash scripts/audit-docs.sh\` locally to check.`;
             github.rest.issues.createComment({
               issue_number: context.issue.number,
               owner: context.repo.owner,