ln-610-docs-auditor
Coordinates 4 documentation audit workers (structure, semantic, fact-check, code comments). Delegates parallel audits, aggregates into docs/project/docs_audit.md.
- License 许可
- MIT
- 最近更新
- 2026-05-02
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- ln-610-docs-auditor
- license
- MIT
- description
- Coordinates 4 documentation audit workers (structure, semantic, fact-check, code comments). Delegates parallel audits, aggregates into docs/project/docs_audit.md.
- allowed-tools
- Read, Grep, Glob, Bash, Skill
03 SKILL.md 正文
Paths: File paths (
shared/,references/,../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.
Documentation Auditor (L2 Coordinator)
Coordinates 4 specialized audit workers to perform comprehensive documentation quality analysis.
Purpose & Scope
- Coordinates 4 audit workers running in parallel:
- ln-611 (documentation structure) — 1 invocation
- ln-612 (semantic content) — N invocations (per target document)
- ln-613 (code comments) — 1 invocation
- ln-614 (fact verification) — 1 invocation
- Detect project type + tech stack ONCE
- Pass shared context to all workers (token-efficient)
- Aggregate worker results into single consolidated report
- Write report to
docs/project/docs_audit.md(file-based, no task creation) - Manual invocation by user or called by ln-100-documents-pipeline
Workflow
- Discovery: Detect project type, tech stack, scan .md files
- Context Build: Build contextStore with output_dir, project_root, tech_stack
- Prepare Output: Create output directory
- Delegate: Invoke 4 workers in parallel
- Aggregate: Collect worker results, calculate overall score
- Context Validation: Post-filter findings
- Write Report: Save to
docs/project/docs_audit.md - Results Log: Append trend row
- Cleanup: Delete worker files
Phase 1: Discovery
Load project metadata:
CLAUDE.md— root of documentation hierarchydocs/README.md— documentation index- Package manifests:
package.json,requirements.txt,go.mod,Cargo.toml - Existing docs in
docs/project/
Extract:
- Programming language(s)
- Major frameworks/libraries
- List of
.mdfiles in project (for ln-611 hierarchy check) - Target documents for semantic audit (for ln-612)
Target documents for ln-612:
FOR doc IN [CLAUDE.md, docs/README.md, docs/documentation_standards.md,
docs/principles.md, docs/project/*.md]:
IF doc exists AND doc NOT IN [docs/tasks/*, docs/reference/*, docs/presentation/*]:
semantic_targets.append(doc)
Phase 2: Build contextStore
{
"tech_stack": {"language": "...", "frameworks": [...]},
"project_root": "...",
"output_dir": "docs/project/.audit/ln-610/{YYYY-MM-DD}"
}
Where {YYYY-MM-DD} is current date (e.g., 2026-03-01).
Phase 3: Prepare Output
mkdir -p {output_dir}
Worker files are cleaned up after consolidation (see Phase 9).
Phase 4: Delegate to Workers
MANDATORY READ: Load shared/references/task_delegation_pattern.md.
All workers in PARALLEL via Agent tool:
| Worker | Invocations | Output |
|---|---|---|
| ln-611-docs-structure-auditor | 1 | {output_dir}/611-structure.md |
| ln-612-semantic-content-auditor | N (per target document) | {output_dir}/612-semantic-{doc-slug}.md |
| ln-613-code-comments-auditor | 1 | {output_dir}/613-code-comments.md |
| ln-614-docs-fact-checker | 1 | {output_dir}/614-fact-checker.md |
ln-614 receives only contextStore and discovers .md files internally. Workers follow the shared file-based audit contract and return compact summaries with report path, score, and severity counts.
Invocation:
// Global workers (ln-611, ln-613, ln-614) — 1 invocation each:
FOR EACH worker IN [ln-611, ln-613, ln-614]:
Agent(description: "Docs audit via " + worker,
prompt: "Execute audit worker.
Step 1: Invoke worker:
Skill(skill: \"" + worker + "\")
CONTEXT:
" + JSON.stringify(contextStore),
subagent_type: "general-purpose")
// Per-document worker (ln-612) — N invocations:
FOR EACH doc IN semantic_targets:
doc_context = { ...contextStore, doc_path: doc }
Agent(description: "Semantic audit " + doc + " via ln-612",
prompt: "Execute audit worker.
Step 1: Invoke worker:
Skill(skill: \"ln-612-semantic-content-auditor\")
CONTEXT:
" + JSON.stringify(doc_context),
subagent_type: "general-purpose")
Phase 5: Aggregate Results
MANDATORY READ: Load shared/references/audit_coordinator_aggregation.md.
Use the shared aggregation pattern for summary parsing, worker report reads, severity rollups, and final report assembly.
Category weights:
| Category | Source | Weight |
|---|---|---|
| Documentation Structure | ln-611 | 25% |
| Semantic Content | ln-612 (avg across docs) | 30% |
| Code Comments | ln-613 | 20% |
| Fact Accuracy | ln-614 | 25% |
Calculate overall score as the weighted average of the 4 categories above.
Phase 6: Context Validation (Post-Filter)
MANDATORY READ: Load shared/references/context_validation.md
Apply Rule 1 + documentation-specific inline filters:
FOR EACH finding WHERE severity IN (HIGH, MEDIUM):
# Rule 1: ADR/Planned Override
IF finding matches ADR → advisory "[Planned: ADR-XXX]"
# Doc-specific: Compression context (from ln-611)
IF Structure finding Cat 3 (Compression):
- Skip if path in references/ or templates/ (reference docs = naturally large)
- Skip if filename contains architecture/design/api_spec
- Skip if tables+lists > 50% of content (already structured)
# Fact-checker: Example/template path exclusion (from ln-614)
IF Fact finding (PATH_NOT_FOUND):
- Path in examples/ or templates/ directory reference → advisory
- Path has placeholder pattern (YOUR_*, <project>, {name}) → remove
# Fact-checker: Planned feature claims (from ln-614)
IF Fact finding (ENTITY_NOT_FOUND, ENDPOINT_NOT_FOUND):
- Entity mentioned in ADR/roadmap as planned → advisory "[Planned: ADR-XXX]"
# Fact-checker: Cross-doc contradiction authority (from ln-614)
IF Fact finding (CROSS_DOC_*_CONFLICT):
- docs/project/ is authority over docs/reference/ → report reference doc
# Comment-specific: Per-category density targets (from ln-613)
IF Comment finding Cat 2 (Density):
- test/ or tests/ → target density 2-10%
- infra/ or config/ or ci/ → target density 5-15%
- business/domain/services → target density 15-25%
Recalculate with per-category target.
# Comment-specific: Complexity context for WHY-not-WHAT (from ln-613)
IF Comment finding Cat 1 (WHY not WHAT):
- If file McCabe complexity > 15 → WHAT comments acceptable
- If file in domain/ or business/ → explanatory comments OK
Downgraded findings → "Advisory Findings" section in report.
Phase 7: Write Report
Write consolidated report to docs/project/docs_audit.md:
## Documentation Audit Report - {DATE}
### Overall Score: X.X/10
| Category | Score | Worker | Issues |
|----------|-------|--------|--------|
| Documentation Structure | X/10 | ln-611 | N issues |
| Semantic Content | X/10 | ln-612 | N issues (across M docs) |
| Code Comments | X/10 | ln-613 | N issues |
| Fact Accuracy | X/10 | ln-614 | N issues |
### Critical Findings
- [ ] **[Category]** `path/file:line` - Issue. **Action:** Fix suggestion.
### Advisory Findings
(Context-validated findings downgraded from MEDIUM/HIGH)
### Recommended Actions
| Priority | Action | Location | Category |
|----------|--------|----------|----------|
| High | ... | ... | ... |
Scoring Algorithm
MANDATORY READ: Load shared/references/audit_scoring.md.
Critical Notes
- Pure coordinator: Does NOT perform any audit checks directly. ALL auditing delegated to workers.
- Fix content, not rules: NEVER modify standards/rules files to make violations pass
- Fact verification via ln-614: Dedicated worker extracts and verifies all claims across ALL docs
- Compress always: Size limits are upper bounds, not targets
- No code in docs: Documents describe algorithms in tables or ASCII diagrams
- Code is truth: When docs contradict code, always update docs
- Delete, don't archive: Legacy content removed, not archived
Phase 8: Append Results Log
MANDATORY READ: Load shared/references/results_log_pattern.md
Append one row to docs/project/.audit/results_log.md with: Skill=ln-610, Metric=overall_score, Scale=0-10, Score from Phase 7 report. Calculate Delta vs previous ln-610 row. Create file with header if missing. Rolling window: max 50 entries.
Phase 9: Cleanup Worker Files
rm -rf {output_dir}
Delete the dated output directory (docs/project/.audit/ln-610/{YYYY-MM-DD}/). The consolidated report and results log already preserve all audit data.
Definition of Done
- Project metadata discovered (tech stack, doc list)
- contextStore built with output_dir =
docs/project/.audit/ln-610/{YYYY-MM-DD} - Output directory created for worker reports
- All 4 workers invoked and completed
- Worker reports aggregated: 4 category scores + overall
- Context Validation applied to all findings
- Consolidated report written to
docs/project/docs_audit.md - Results log row appended to
docs/project/.audit/results_log.md - Worker output directory cleaned up after consolidation
Phase 10: Meta-Analysis
MANDATORY READ: Load shared/references/meta_analysis_protocol.md
Skill type: review-coordinator (workers only). Run after all phases complete. Output to chat using the review-coordinator — workers only format.
Reference Files
- Context validation rules:
shared/references/context_validation.md - Task delegation pattern:
shared/references/task_delegation_pattern.md - Aggregation pattern:
shared/references/audit_coordinator_aggregation.md
Version: 5.0.0 Last Updated: 2026-03-01
04 同仓库更多 Skills
zarr-python
Chunked N-D arrays for cloud storage. Compressed arrays, parallel I/O, S3/GCS integration, NumPy/Dask/Xarray compatible, for large-scale scientific computing pipelines.
zabbix
Zabbix monitoring system automation via API and Python. Use when: (1) Managing hosts, templates, items, triggers, or host groups, (2) Automating monitoring configuration, (3) Sending data via Zabbix trapper/sender, (4) Querying historical data or events, (5) Bulk operations on Zabbix objects, (6) Maintenance window management, (7) User/permission management
x-twitter-growth
X/Twitter growth engine for building audience, crafting viral content, and analyzing engagement. Use when the user wants to grow on X/Twitter, write tweets or threads, analyze their X profile, research competitors on X, plan a posting strategy, or optimize engagement. Complements social-content (generic multi-platform) with X-specific depth: algorithm mechanics, thread engineering, reply strategy, profile optimization, and competitive intelligence via web search.
what-if-oracle
Run structured What-If scenario analysis with multi-branch possibility exploration. Use this skill when the user asks speculative questions like "what if...", "what would happen if...", "what are the possibilities", "explore scenarios", "scenario analysis", "possibility space", "what could go wrong", "best case / worst case", "risk analysis", "contingency planning", "strategic options", or any question about uncertain futures. Also trigger when the user faces a fork-in-the-road decision, wants to stress-test an idea, or needs to think through consequences before committing.
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
venue-templates
Access comprehensive LaTeX templates, formatting requirements, and submission guidelines for major scientific publication venues (Nature, Science, PLOS, IEEE, ACM), academic conferences (NeurIPS, ICML, CVPR, CHI), research posters, and grant proposals (NSF, NIH, DOE, DARPA). This skill should be used when preparing manuscripts for journal submission, conference papers, research posters, or grant proposals and need venue-specific formatting requirements and templates.