playbooks

home / skills / duc01226 / easyplatform / docs-update

docs-update skill

/.claude/skills/docs-update

This skill analyzes the codebase and updates documentation across README and docs files to reflect current architecture and standards.

npx playbooks add skill duc01226/easyplatform --skill docs-update

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.5 KB
---
name: docs-update
description: "[Docs] ⚡⚡⚡ Analyze the codebase and update documentation"
infer: true
---

## Phase 1: Parallel Codebase Scouting

**You (main agent) must spawn scouts** - subagents cannot spawn subagents.

1. Run `ls -la` to identify actual project directories
2. Spawn 2-4 `scout-external` (preferred, uses Gemini 2M context) or `scout` (fallback) via Task tool
3. Target directories **that actually exist** - adapt to project structure, don't hardcode paths
4. Merge scout results into context summary

## Phase 2: Documentation Update (docs-manager Agent)

Pass the gathered file list to `docs-manager` agent to update documentation:
- `README.md`: Update README (keep it under 300 lines)
- `docs/project-overview-pdr.md`: Update project overview and PDR (Product Development Requirements)
- `docs/codebase-summary.md`: Update codebase summary
- `docs/code-standards.md`: Update codebase structure and code standards
- `docs/system-architecture.md`: Update system architecture
- `docs/project-roadmap.md`: Update project roadmap
- `docs/deployment-guide.md` [optional]: Update deployment guide
- `docs/design-guidelines.md` [optional]: Update design guidelines

## Additional requests
<additional_requests>
  $ARGUMENTS
</additional_requests>

## [CRITICAL] Code Evidence Requirements

All documentation MUST follow evidence rules from `.claude/skills/feature-docs/SKILL.md` → `[CRITICAL] MANDATORY CODE EVIDENCE RULE`

### Quick Reference
- **Format**: `**Evidence**: {FilePath}:{LineNumber}`
- **Status**: ✅ Verified / ⚠️ Stale / ❌ Missing
- **Verification**: 3-pass verification required before completion

### Stale Evidence Detection

When updating documentation:
1. **Read actual source files** at claimed line numbers
2. **Verify evidence matches** documented behavior
3. **Update stale references** - mark with ⚠️ if line numbers changed
4. **Refresh line numbers** after code changes

### Evidence Verification Table (Required)
| Entity/Component | Documented Lines | Actual Lines | Status     |
| ---------------- | ---------------- | ------------ | ---------- |
| `Entity.cs`      | L6-15            | L6-15        | ✅ Verified |
| `Handler.cs`     | L45-60           | L52-67       | ⚠️ Stale    |

## Important
- Use `docs/` directory as the source of truth for documentation.

**IMPORTANT**: **Do not** start implementing.

## IMPORTANT Task Planning Notes

- Always plan and break many small todo tasks
- Always add a final review todo task to review the works done at the end to find any fix or enhancement needed

Overview

This skill analyzes a C# codebase, coordinates lightweight scouting agents, and produces evidence-backed documentation updates under docs/. It plans the work, merges scout findings, and hands a verified file list to a docs-manager agent to update project documents. The output focuses on traceable claims and a final review pass to ensure accuracy.

How this skill works

First, the skill spawns 2–4 scout agents to discover the real directory layout and gather file lists and relevant code snippets. It merges scout outputs into a single context summary and passes that list to a docs-manager agent which updates the specified docs/ files. All documentation changes must include code evidence references and undergo a three-pass verification before being marked complete.

When to use it

  • When you need accurate, evidence-backed updates to docs/ based on current code.
  • When onboarding contributors who require an updated project overview and architecture docs.
  • When preparing a release and needing a synchronized project roadmap and system architecture.
  • When code structure changed and documentation must reflect exact line-level evidence.
  • When you want an automated plan broken into many small actionable documentation tasks.

Best practices

  • Spawn 2–4 scout agents and target only directories that actually exist; do not hardcode paths.
  • Merge scout findings into a concise context summary before any documentation edits.
  • Attach code evidence for every claim using the format: **Evidence**: {FilePath}:{LineNumber} with status markers.
  • Perform a three-pass verification for every evidence reference: read file, confirm behavior matches claim, refresh line numbers if needed.
  • Break work into many small TODO tasks and include a final review task to validate consistency and stale references.

Example use cases

  • Scan an unfamiliar C# solution to generate an accurate codebase-summary and system-architecture document.
  • Update design-guidelines and code-standards after a refactor, with line-level evidence for key changes.
  • Produce a project-overview and product development requirements document grounded in verified code snippets.
  • Create a deployment-guide draft by collecting existing deployment scripts and verifying their locations and lines.
  • Run a documentation refresh sprint where scouts gather file lists and docs-manager consolidates updates into docs/.

FAQ

How many scout agents should be spawned?

Spawn between 2 and 4 scouts; prefer scout-external but fall back to scout if needed.

What format must code evidence use?

Use the format **Evidence**: {FilePath}:{LineNumber} and mark status as ✅ Verified / ⚠️ Stale / ❌ Missing after three-pass verification.