docs-context — Context Loader & Doc Synchronizer

Manages reading and writing of project documentation, ensuring correct contextual constraints during development and keeping docs in sync with code afterward.

Contents

• Positioning, conflict priority, context correction taxonomy
• Document Paths (5 doc types under docs/)
• BCU Splitting Principle (decision flow + section-omission rule)
• Modes & Triggers (Read / Write criteria, Removal & Rollback Sync)
• Read Mode: always-load, task-type loading, BCU / ADR resolution, three context scenarios, post-load behavior
• Write Mode: doc sync checklist, slug selection, ADR write flow, sync execution steps
• Handling Missing Documents (scope, init flow, template mapping)
• Sync Summary Format (Updated / Created / Deleted / Declined / Skipped / No Update / Shared / Needs Confirmation)

Positioning: Super Base Context

docs-context is the Super Base Context for Agent Coding — structured project docs, task-aware Read Mode, bidirectional Write Mode. The remainder of this file specifies each.

Conflict priority (when this skill's guidance collides with other instructions in the same turn): explicit user instruction > docs-context.

Context Correction, Completion, and Reconstruction

Three scenarios in which docs-context restores the agent's project context — combined documents + code/comment scanning fills the gap when docs alone are insufficient.

• Correction — Not limited to enforcing constraints on generated code. When context degrades due to long-conversation attention decay, context compression inaccuracies, or accumulated drift, the agent can re-read the relevant documents and scan the actual codebase to restore an accurate understanding. Documents act as the ground truth that pulls distorted context back on track.
• Completion — When the agent lacks context for the current task, documents provide the structural knowledge (architecture, module boundaries, dependencies, constraints), while code and comment scanning fills in the implementation specifics that documents may not cover.
• Reconstruction — When starting a new session or opening a project for the first time, the agent has zero knowledge of the project. By triggering this skill, the agent loads the relevant documents (backbone) and combines them with code and comment scanning to reconstruct a complete understanding of the project from scratch.

Document Paths

All documents are located under the workspace docs/ directory:

No README / index files under docs/modules/ or docs/decisions/. Use Glob to enumerate; read frontmatter / first-line responsibility on demand.

BCU Splitting Principle

A docs/modules/<bcu-slug>.md file represents one Business Capability Unit (BCU). A BCU must satisfy all 7 conditions:

1. Has an explicit business goal
2. Has an independent business flow
3. Has a relatively stable context boundary
4. Can be developed, modified, and tested independently
5. Modifications primarily affect this single business chain
6. Impact scope can be analyzed independently
7. An independent development plan can be generated for it

Do NOT split by: microservice · Controller · API · technical module · database table. DO split by: real business chain · actual development task boundary · parallel-development unit.

BCU Splitting Decision Flow

When in doubt whether to merge or split, run this 3-question test:

Any "no" → merge. All three "yes" → split. Default to conservative merging — splitting later is cheap (BCU files are independent); splitting too early creates orphaned tiny files. Split only when independent-evolution signals show up: separate owner, separate schedule, separate test suite, modifications no longer cascade.

Worked example — consumer-side payment: a typical "consumer pay" BCU bundles {payment initiation API + sync order query + upstream async callback + scheduled / MQ status reconciliation} into ONE file (e.g. consumer-pay.md) — they share one business goal and one state machine, and they are almost always modified together. Split out to a separate BCU only when "reconciliation crosses multiple BCUs", "order query is independently productized", or "callback routing is independently maintained" — i.e. when the merge condition stops holding.

Diagrams in BCU files

A BCU file uses two layers of diagrams, each with its own purpose. Both layers respect the section-omission rule — never draw a diagram for its own sake.

Layer 1 — Per-entry tracing diagrams (live inside ## Implementation)

Each entry-point item — HTTP API (inbound), MQ Consumption, Scheduled Task, Third-party Callback — MAY carry a tracing diagram of this entry's full call chain (services / RPC / MQ Production / DB / external systems / resources).

Format — primary: ASCII span tree, supplementary: Mermaid sequenceDiagram:

• Primary (default) — ASCII span tree of the factual call chain, mirroring distributed-tracing UIs (SkyWalking / Jaeger / etc.): hierarchical indentation showing parent → child calls.
  • Compact, diff-friendly, readable in plain text and in any Markdown renderer.
  • Use box-drawing chars (├── / └── / │) or plain ASCII (+--).
  • Each line: one hop (service.method / DB op / RPC / MQ produce / external call) with its result if non-obvious.
• Supplementary (optional) — when the entry is async / multi-roundtrip / has callbacks that the tree shape can't naturally express, ADD a Mermaid sequenceDiagram BELOW the tree for global overview. Don't replace the tree — add alongside. The tree is the factual chain; the sequence diagram is the temporal overview.
• Trivial entries — omit both. Single read-and-return query, single SQL insert: no diagram.

Two rules apply together — optional + complete-when-present:

• Optional — not every entry needs a diagram. Trivial entries stay diagram-free.
• Complete when present — if a diagram (tree or sequence) is drawn, it MUST cover every real hop end-to-end. Half-drawn / placeholder / partial-chain diagrams are forbidden.

ASCII span tree shape:

ENTRY: [protocol/method] [name]
├── [Service.method] (this servi