Docs Context

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: | Document | Path | Content | |----------|------|---------| | Architecture | docs/architecture.md | Workspace directory structure, project background, system architecture, service-level topology, constraints, future plans | | Tech Stack | docs/tech-stack.md | Framework versions, dependency constraints, environment requirements, AI code generation limits | | Coding Standards | docs/coding.md | Coding standards, naming conventions, API design standards, error handling, logging standards, testing standards | | Module Registry | docs/modules/.md | One file per Business Capability Unit (BCU). Each BCU file holds a single business capability's implementation list (HTTP / RPC / MQ / scheduled tasks / third-party callbacks / DB tables / frontend pages), flow, state transitions, local upstream/downstream, external dependencies, related business flows. Slug names a business capability (e.g. create-order, refund, consumer-pay), NOT a microservice / Controller / package / table | | Decision Records | docs/decisions/ADR-.md | One file per architecture decision (ADR). Slug-only filenames (no numeric prefix, no date prefix). Date lives in frontmatter |

> 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/.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:

| Q | If answer is "no" → | |---|---------------------| | Q1: When modifying A, do you usually NOT need to touch B/C/D? | merge into one BCU | | Q2: Can A deliver business value standalone, decoupled from B/C/D? | merge | | Q3: Does A have a separate owner / schedule / test suite? | merge |

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.

| Entry-point complexity | Format | |---|---| | Trivial single-step (read-and-return / single insert) | Omit | | Linear / synchronous chain (any depth) | ASCII span tree | | Async / multi-roundtrip / external callbacks where temporal order matters | ASCII span tree + supplementary Mermaid sequenceDiagram |

ASCII span tree shape:

ENTRY: [protocol/method] [name]
├── [Service.method] (this service)
│   ├── DB.[table] insert/update
│   └── [DownstreamService].[op] (RPC) → [result]
├── [ExternalGateway].[op] (HTTP/SDK) → [result]
└── MQ produce [topic]

Non-entry items NEVER carry their own diagram: outbound RPC, MQ Production, Database tables touched, Frontend page, State management. They appear as nodes inside the calling entry's tree. A separate diagram for these is redundant and is forbidden.

Layer 2 — BCU business flow(s) (the ## Flow section, 0 / 1 / N diagrams)

The business-level view: how front-end interactions, business steps, and state transitions weave through the entry points to deliver the BCU's value. This is the business view, NOT a technical hop trace.

A BCU may carry 0, 1, or N business-flow diagrams (1-to-many relationship):

| BCU business-flow situation | Shape | |---|---| | Single-entry BCU, business flow already obvious from ## Implementation | 0 — omit the entire ## Flow section | | One coherent business flow | 1 — one diagram directly under ## Flow | | Multiple distinct business sub-flows (e.g. passive-scan vs aggregated-scan vs refund) | N — ### headings, one diagram per sub-flow. Don't bloat one diagram with mutually exclusive branches. |

Format per diagram: Mermaid sequenceDiagram or flowchart describing business steps; numbered text when truly simple.

Non-redundancy contract:

• Layer 1 nodes = services / RPC / resources / externals (technical hops)
• Layer 2 nodes = business steps / user actions / state transitions
• Layer 2 references Layer 1 by entry name (e.g. "calls POST /pay/passive-scan"); it does NOT redraw the entry's internal hops

Inclusion boundary (both layers):

• IN: services / resources / externals that this BCU itself invokes during its chain
• OUT: services unrelated to this BCU's chain
• OUT: the system-wide service topology diagram — that belongs in docs/architecture.md

Why this split: a multi-entry BCU (e.g. consumer pay with passive-scan / aggregated-scan / async callback / reconciliation job) needs per-entry tracing for technical clarity AND business-flow diagrams for business clarity. Forcing both into one diagram either bloats it beyond reading or loses one of the two views. Splitting cleanly maps to "what each entry does technically" + "how the business strings them together".

Section-Omission Rule (hard)

Inside a BCU file, only the skeleton sections are mandatory: title (# ), header lines (Status / Owning service), ## Business Goal, ## Implementation (with at least one entry). All other sections are conditional: ## Flow, ## State Transitions, ## Upstream / Downstream, ## External Dependencies, ## Related Business Flows, ## Risks / Constraints, ## Notes / Gotchas — omit the entire section if the BCU has no relevant content. Do NOT keep empty headings, do NOT write N/A / TBD, do NOT leave placeholder bullets. Same rule applies to ## Implementation sub-bullets — list only what actually exists.

Modes & Triggers

Two modes

| Mode | When | Responsibility | |------|------|----------------| | Read | Before any project-related work | Load relevant docs, establish constraints | | Write | After code/decisions land / before commit | Sync affected docs (forward AND reverse) |

Read Mode triggers

Root criterion: does the task need to reference how the project actually works today? If yes, trigger Read Mode.

Triggers on any of:

• Code work: write/modify/add/remove/delete/deprecate code, implement, develop, integrate
• Bugfix / refactor: fix bug, debug, refactor, optimize, improvement plan
• Tests: write tests, unit/integration tests, test strategy / plan
• Database: migration, schema, DDL, add/drop column, add/drop table
• Design / review: architecture design / review, microservice split, module boundary discussion, detailed spec, state-machine design, business-flow mapping, data-flow design
• Selection / decisions: tech selection, dependency choice, upgrade evaluation, ADR authoring, decision comparison
• Research / inventory: historical decision research ("why did we choose X"), past-solution analysis, current architecture inventory, current dependency inventory, code review
• Performance / security: performance design, capacity planning, security design, threat modeling, vulnerability fix
• API / integration: API design, integration, contract negotiation
• Any spec / plan / design / ADR that references current project state — regardless of detail level

> Does NOT trigger Read Mode: brainstorming with no project reference, generic-knowledge questions (e.g. "how does HashMap work in Java"), pure read-only code explanations. > When uncertain, default to Read Mode (defensive).

Write Mode triggers

Single criterion: current code/decision state has a net delta vs. the last-synced doc state.

Net delta scope (bidirectional):

• Forward: additions / modifications of landed content (code, config, SQL, build scripts, ADR decisions)
• Reverse: removals / deprecations of previously-synced code or decisions (docs must shrink to match)
• Rollback: rollbacks of previously-synced content (docs revert accordingly)

When it fires:

• User signals: sync docs / update docs / done / completed / ready to commit / feature done / pre-commit check / record this decision
• [auto] Agent self-trigger: MUST fire right before the agent's final task-completion reply — do not wait for the user

Does NOT fire on (any one match → skip):

1. Partial edits while the task is still in progress
2. Mid-task progress updates
3. Read-only / Q&A tasks
4. Brainstorming or generic-knowledge questions with no project state referenced
5. High-level plan with no code/decision landed (note: detailed spec still triggers Read Mode; this only excludes Write Mode)
6. In-session try-and-undo that left no net change
7. Already synced this round with no new changes after

Removal & Rollback Sync (a first-class concept)

docs-context syncs in both directions: when code is added, docs grow; when code or decisions are removed / rolled back, docs shrink to match.

| Code or decision change | Doc action | |------------|-----------| | Delete a BCU's code entirely | Delete docs/modules/.md | | Delete a single HTTP API / RPC / MQ producer-consumer / scheduled task / third-party callback inside a BCU | Update the BCU file's ## Implementation section | | Drop a database table or column | Update affected BCU file's ## Implementation (Database tables touched line) and the header **Database tables touched** line | | Overturn a previously-merged decision | Delete docs/decisions/ADR-.md (history lives in git) | | Roll back a previously-recorded refactor | Restore the affected sections (or whole BCU file) to the rolled-back state | | Remove a cross-BCU dependency | Bidirectional sync: delete this BCU file's ## Upstream / Downstream entry AND the counterpart BCU file's ## Upstream / Downstream entry |

Distinguishing removal from in-session try-and-undo:

| Scenario | Net delta | Write Mode | |------|-------|----------| | Code was synced → now removed | Yes | Triggers (reverse sync) | | In-session add → in-session delete → net delta zero | No | Skips | | In-session add → in-session delete, but other parts still have net delta | Yes | Triggers (only for landed parts) |

Detection method: git diff against the last-synced commit; or working tree vs HEAD.

> Do not maintain Deprecated / Superseded states. Removal means the doc section is deleted (ADR file deleted, capability section deleted). History is recoverable via git log -- docs/.

Read Mode: Context Loading

Loading Context

Always Load

Every time read mode is triggered, MUST load:

• docs/coding.md — Coding standards are the baseline constraint for all tasks

Additional Loading by Task Type

modules/* and decisions/* shortcuts a

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lujiafa
• Source: lujiafa/houtu-project-skills
• License: MIT

Install and usage instructions live in the source repository linked above.