Imported from Atiqul-Islam/genesis (skills/docs-update/SKILL.md). Install upstream with npx skills add Atiqul-Islam/genesis --skill docs-update. Copyright stays with the author.

Docs Update Skill

Update docs/architecture.md (and optionally docs/design-decisions.md) to reflect the current state of the project. Optimized for speed — uses parallel reads, Glob for file lists, and incremental Edit instead of full regeneration.

Usage

/docs-update                  # Incremental update of architecture.md only
/docs-update --full           # Full regeneration of both docs (architecture + design decisions)
/docs-update --decisions      # Include design-decisions.md update

Default behavior (no args): Update docs/architecture.md only, using targeted Edits. This is the fast path for normal development.

Workflow

Phase 1a: Cheap state on the main agent (parallel)

Issue ALL of these in a single response, in parallel:

1. Glob("test/specs/*.md") — spec file names
2. Glob("test/features/*.feature") — feature file names
3. Glob("test/steps/**/*.{ts,py}") — step definition file names
4. Glob("config/*") — config file names (if config/ exists)
5. Glob("src/**/*", head_limit: 200) — source file names (and size gate for Phase 1b)
6. Read("docs/architecture.md") — needed to Edit in Phase 2
7. Read("README.md") — if it exists

If --full or --decisions was passed, also read: 8. Read("docs/design-decisions.md") — existing decisions doc

Files NOT read in full (Glob names only — saves file reads):

• test/specs/*.md — only file names and count matter
• test/features/*.feature — scenario names come from Grep, not full reads
• test/steps/**/* — only file names and count matter
• CLAUDE.md — referenced, not duplicated
• docs/spec-driven-development.md — referenced, not duplicated

Phase 1b: Delegate architecture survey to an Explore subagent

Skip this phase if the Phase 1a Glob("src/**/*") returned fewer than ~30 files. On small projects the main agent can read source files directly without pressure.

Otherwise, spawn an Explore subagent via the Task tool (subagent_type: "Explore", thoroughness: medium). Use this prompt verbatim:

Survey this project and return a concise architecture brief covering:

• (a) Entry points and how the app runs
• (b) Main modules and their roles
• (c) Config/settings loading
• (d) Test infrastructure wiring
• (e) Key runtime dependencies

Each item ≤6 lines. Do not paste source code — describe. Cap total output at 40 lines.

Main agent uses the Phase 1a reads + the Phase 1b brief to drive Phase 2 edits.

Phase 1c: Targeted reads (only if needed)

After Phase 1a/1b, only if Phase 2 needs more detail:

9. Read config files only if their sections need updating
10. Read package.json or pyproject.toml only if dependencies section needs updating

Phase 2: Update Docs

For docs/architecture.md:

1. Compare gathered state against each section of the existing doc
2. Use Edit to update only sections that have changed:
   • New/removed files in Directory Structure
   • Scenario count changes in Test Infrastructure
   • New dependencies
   • Runtime architecture changes (if entry points changed significantly)
3. Always update the "Last updated" date line
4. Fall back to Write only if the file doesn't exist yet

For docs/design-decisions.md (only with --full or --decisions):

1. Compare current architecture against existing decisions
2. Use Edit to add new decisions or update changed ones
3. Always update the "Last updated" date line
4. Fall back to Write only if the file doesn't exist yet

Section template for architecture.md (used only when creating from scratch):

# Project Architecture

> Auto-generated by `/docs-update`. Last updated: <current date>
> Source of truth for system architecture. Optimized for Claude Code context loading.

## System Overview
<!-- 2-3 sentences: what the project is, what it does -->

## Directory Structure
<!-- Annotated tree with purpose of each directory and key files -->

## Runtime Architecture
<!-- How the system runs: entry points, data flow, external dependencies -->
<!-- Include Mermaid sequence or flowchart diagram if helpful -->

## Configuration
<!-- Config files, environment variables, settings -->

## Test Infrastructure
<!-- How BDD tests work, step definition patterns, test data setup -->

## Dependencies
<!-- Key dependencies and their roles -->

Section template for design-decisions.md (used only when creating from scratch):

# Design Decisions

> Auto-generated by `/docs-update`. Last updated: <current date>
> Key design choices and their rationale.

## Decision Log

### <Decision Title>
- **Status**: Active | Superseded | Proposed
- **Context**: Why this decision was needed
- **Decision**: What was decided
- **Rationale**: Why this choice over alternatives
- **Consequences**: What this enables or constrains

Phase 3: Report

Report what was updated:

• List which sections were edited (or "no changes needed") for each doc
• Note any new files/components discovered
• If --full or --decisions was NOT passed, remind that design-decisions.md was skipped

Writing Guidelines

• Use bullet points over paragraphs
• Include file paths so Claude knows where to look
• Use Mermaid diagrams for component relationships and data flow
• Be concise — this is a reference doc, not a tutorial
• Do NOT duplicate content from CLAUDE.md or docs/spec-driven-development.md
• Focus on architecture facts: what exists, how it connects, where to find things
• Do NOT include test/spec counts, scenario counts, pass/fail status — these change constantly

Important Rules

• Never modify docs/spec-driven-development.md — manually maintained
• Never duplicate content from CLAUDE.md — reference it instead
• Always include the "Last updated" date in generated docs
• Always use Mermaid for diagrams
• Prefer Edit over Write — only use Write when creating a doc from scratch
• Minimize file reads — use Glob for file lists, Grep for counts, Read only for source files that inform architecture

WORKFLOW COMPLETE

After updating docs and presenting the summary, this skill workflow is FINISHED. Return to normal conversation mode.