Skip to content

mgiovani/ai-arsenal / skills/docs-update

docs-update

Verified

Refresh existing docs (architecture, onboarding, data-model, deployment, security, contributing) so they match the current codebase, verifying every claim against real code instead of guessing. Use when the user says docs are stale, asks to sync docs with recent code changes, update a specific doc file, or update a whole category (core/data/infrastructure/development) after a refactor or schema change. Not for creating docs that don't exist yet (use docs-init) or scoring/auditing doc health without editing (use docs-check).

FileKindSize
SKILL.mdskill md7.8 KB
evals/evals.jsonconfig2.7 KB
evals/trigger-eval.jsonconfig1.9 KB
references/change-detection.mdmarkdown1.6 KB
references/update-strategies.mdmarkdown2.3 KB

references/update-strategies.md

View on GitHub
# Update Strategies

Parallel subagent pattern and per-document-type checklist for multi-document updates
(SKILL.md Phase 3, "all" or "category" mode). For a single document, SKILL.md's inline
one-pass approach is enough, this file is only for the concurrent case.

## Spawning One Agent Per Document

```
Agent 1 - Architecture Update:
- prompt: "Update docs/architecture.md. Read it fully, grep the codebase to verify every
  claim (service names, counts, tech stack), remove anything that can't be confirmed,
  add missing components found in the code, preserve custom sections."
- subagent_type: "general-purpose"

Agent 2 - Data Model Update:
- prompt: "Update docs/data-model.md. Find actual ORM models, verify the ER diagram
  matches them, preserve custom sections."
- subagent_type: "general-purpose"

Agent 3 - Onboarding Update:
- prompt: "Update docs/onboarding.md. Verify every setup command and file path
  mentioned actually exists/runs, preserve custom sections."
- subagent_type: "general-purpose"
```

If no Task/subagent tool is available, run each of these prompts as a sequential
read-verify-write pass instead: same checklist, one document at a time.

## Per-Document-Type Checklist

Architecture: scan for services/modules/components, identify databases/caches/queues,
map data flow, regenerate the architecture diagram, preserve custom architecture notes.

Data model: find ORM models, extract entities and relationships, regenerate the ER
diagram, document constraints, preserve custom data notes.

Deployment: find Docker/K8s configs, map services to infrastructure, document the
CI/CD pipeline, update environment configs, preserve custom deployment notes.

Security: find auth/authz code, map security boundaries, document encryption points,
identify security controls, preserve custom security notes.

## Example Output: Category Update

```
Core Documentation Category Updated

Updated (2 docs):
  docs/architecture.md (added microservices diagram — 5 services found in src/services/)
  docs/onboarding.md (setup instructions updated for new tooling in package.json)

Verified but unchanged (1 doc):
  docs/adr/ (5 records, all still accurate)

Next Steps:
  1. Review updated documentation
  2. Regenerate diagrams if code changes again: docs-diagram arch
  3. Create a new ADR for the recent decision: docs-adr "Decision Title"
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall