progressive-doc-architect

name

progressive-doc-architect

description

create or refactor repository documentation and agents files using progressive disclosure. use when chatgpt needs to add new docs, split oversized docs, build indexes, or maintain readme and agents structures so coding agents can navigate a codebase without loading everything at once. optimized for repositories that want a hard maximum of three layers, explicit read triggers, compact routing docs, and leaf docs that contain the detailed implementation facts.

Progressive Doc Architect

Overview

Use this skill to make repository documentation behave like a router instead of a dump. New docs must help another ChatGPT or coding agent decide whether to stop, descend, or redirect without loading the whole tree.

Core contract

Follow references/pd3-contract.md.

The non-negotiables are:

1. Keep the main path from root to leaf at three layers or fewer.
2. Add a hidden docmeta block at the top of every governed routing doc and AGENTS.md file.
3. Make entry and domain docs route. Make leaf docs explain.
4. Use AGENTS.md for local filesystem navigation, mutation boundaries, and search strategy. Do not restate full architecture there.
5. Use children only for structural descendants. Links to sibling entry docs or sideways references belong in the body, not in children.
6. Update the parent document and docs/catalog.yaml whenever a governed doc is added, removed, or moved.
7. Split by decision value, not by prose length alone.

Choose the artifact type first

Before writing, classify the request into exactly one of these artifact types:

• entry doc: first stop for a repo or a major surface. Examples: README.md, docs/INDEX.md, root AGENTS.md.
• domain index: second-layer router for one stable area such as runtime, code, product, transport, or storage.
• leaf doc: terminal explanation for one subsystem or one decision surface.
• directory AGENTS.md: local instructions for a directory and its immediate children.

If the requested document would create a fourth layer, restructure the parent or merge adjacent leaves instead of adding depth.

Workflow

1. Inspect the intended parent, siblings, and source directories before writing.
2. Decide whether the new artifact is an entry doc, domain index, leaf doc, or directory AGENTS.md.
3. Write or update the hidden docmeta block using the templates in references/templates.md.
4. Keep routing docs short. If an entry or domain doc starts containing procedures, control flow, or large factual explanations, move those details into a leaf doc.
5. Put detailed facts only in the leaf doc closest to the directories named in source_of_truth.
6. Update structural parent children links and docs/catalog.yaml. Keep sibling or sideways references in ordinary body links.
7. Run python scripts/validate_doc_contract.py <repo-root>.
8. Fix all validation errors. Treat warnings as prompts to simplify the structure.

Writing rules

• Prefer task and decision boundaries over team boundaries or historical chronology.
• Each routing doc must answer four questions quickly:
  • what does this node cover?
  • when should the reader open it?
  • when should the reader skip it?
  • which child should the reader open next?
• Each leaf doc must answer four questions clearly:
  • what subsystem or decision surface does this cover?
  • which files and directories are the source of truth?
  • what is the main control flow or data flow?
  • what edits are safe here, and what requires escalation?
• Use short bullets and path lists in routing docs. Use prose in leaf docs only when the detail matters.
• Avoid hidden fourth layers through long “see also” chains. Related links are fine, but the main path from root to leaf must remain three hops or fewer.
• When two docs repeat the same factual explanation, keep one as the source of truth and convert the other into a pointer.

AGENTS.md rules

Use AGENTS.md only for repository navigation, mutation boundaries, and local search strategy.

A directory AGENTS.md should include:

• directory purpose
• read-when triggers
• skip-when triggers
• local map of important files or subdirectories
• search order
• edit safety notes
• escalation targets

Keep it coupled to the directory it lives in.

Resources

• references/pd3-contract.md: the doctrine, metadata schema, and split rules.
• references/templates.md: copy-paste templates for entry docs, domain indexes, leaf docs, and AGENTS.md files.
• references/checklist.md: pre-flight checklist, review checklist, and anti-patterns.
• scripts/validate_doc_contract.py: validator for docmeta, layer depth, parent-child consistency, and catalog coverage.

Validation

Run:

python scripts/validate_doc_contract.py <repo-root>

Use strict mode before finalizing a larger refactor:

python scripts/validate_doc_contract.py <repo-root> --strict

Strict mode is useful when you want every governed document to be present in docs/catalog.yaml and every docs file under docs/ to follow the contract.