maintain-dev-docs

Maintain Dev Docs

Purpose

Use this skill to set up or maintain a repository-specific docs/dev documentation system for correct code-writing guidance. The skill owns only the target repository's docs/dev documents.

Do not make target-repo docs/designs, docs/brainstorms, docs/solutions, traceability.md, or completion-audit.md default outputs. If the work needs those artifacts, report that a separate requirements/design workflow is needed.

Core Workflow

1. Read target repo instructions and existing docs before writing anything.
2. Identify the operating mode from the request and repo state.
3. Scan the target repo baseline using references/repo-scan.md.
4. If docs/dev is missing or empty, scaffold only neutral README skeletons from assets/docs-dev/.
5. Decide dynamic detailed docs from target repo evidence, not from this skill's source repo.
6. Cross-validate local patterns before documenting them as current rules.
7. Write current rules under architecture/, engineering/, or domain/; write future proposals under evolution/.
8. Record baseline sources, changed docs, scenario coverage, external evidence, decisions, and gaps inside docs/dev.
9. Verify the work did not create target-repo design-package files by default.

Operating Modes

Select only the modes needed for the current request.

• init: docs/dev is absent or empty. Read references/docs-dev-structure.md and use the neutral assets.
• baseline: The user asks to understand or document the repo's current stack, structure, or conventions. Read references/repo-scan.md.
• pattern-research: The user asks for best patterns, anti-patterns, examples, design patterns, or code-writing guidance. Read references/pattern-research.md and references/example-validation.md.
• dependency-change: Dependencies, package files, lockfiles, APIs, or external SDKs changed. Use repo scan plus pattern research for the changed dependency only.
• architecture-change: Module boundaries, public APIs, import direction, folder structure, or runtime boundaries changed. Read references/docs-dev-structure.md and references/decision-records.md.
• domain-change: Domain terms, business rules, states, or invariants changed. Update docs/dev/domain and relevant gaps.
• audit: The user asks whether docs/dev is stale, incomplete, inconsistent, or valid. Read references/audit-evidence.md.
• decision: A durable code-writing or documentation decision is made or superseded. Read references/decision-records.md.
• ai-rules: AI reading order, uncertainty handling, or coding-agent rules need updates. Update docs/dev/ai.

Reference Loading

• Always load references/workflow.md for non-trivial work.
• Load references/repo-scan.md before deriving repo-specific guidance.
• Load references/docs-dev-structure.md before creating or moving docs/dev files.
• Load references/pattern-research.md and references/example-validation.md before writing best/anti-pattern examples.
• Load references/decision-records.md before adding or superseding decisions.
• Load references/audit-evidence.md before claiming completion or auditing existing docs.

User Confirmation Boundaries

Continue with a documented default for reversible local choices such as whether to keep a topic in a folder README or split it into a detailed file.

Ask before:

• deleting existing docs instead of superseding or moving them;
• adding new dependencies, scripts, hooks, CI, or automation;
• creating files outside docs/dev;
• treating a future proposal as an accepted current rule;
• changing a target repo's public API, architecture, security posture, or data-retention behavior.

Output Boundary

Allowed default outputs:

• docs/dev/README.md
• docs/dev/architecture/**
• docs/dev/engineering/**
• docs/dev/domain/**
• docs/dev/evolution/**
• docs/dev/ai/**
• docs/dev/decisions/**

Not default outputs:

• docs/designs/**
• docs/brainstorms/**
• docs/solutions/**
• traceability.md
• completion-audit.md

If completion evidence is needed, write it into docs/dev root or folder READMEs, docs/dev/ai/README.md, or docs/dev/decisions/README.md.