| name | bridge-docs-discipline |
| description | Use when editing `bridge/docs/spec.md`, `bridge/docs/zk-l2-bridge-design-notes.md`, or adjacent bridge documentation in this repository. It enforces the role split that `spec.md` is a math-first abstract model for theory and paper work, while `zk-l2-bridge-design-notes.md` is a stable high-level architecture document for future developer docs and should avoid volatile implementation detail. |
Bridge Docs Discipline
Use this skill whenever a task touches bridge documentation and there is any risk of
mixing up the roles of:
bridge/docs/spec.mdbridge/docs/zk-l2-bridge-design-notes.mdbridge/docs/current-implementation.md
Documentation Writing Quality
Every sentence, paragraph, section, and document must have a logical flow. The writing
must carry the reader smoothly from the problem or thesis, through the reasoning, to the
conclusion. Do not leave a statement hanging after presenting a fact. Explain why the
fact matters, what it enables, what risk it creates, or what conclusion follows from it.
Each paragraph should give the reader a reason to continue. Avoid writing lists of true
statements that do not explain their own relevance. Prefer a progression such as:
- introduce the problem, concept, or claim
- define the terms needed to understand it
- explain the mechanism or reasoning
- give a concrete example when the concept is not common
- state the resulting implication or conclusion
For any concept or term that is not ordinary, universal, or already established in the
same document, define it accurately and clearly before relying on it. When a definition
is subtle, include an example that shows how the term is used in the system. The example
should reduce ambiguity, not add another unexplained abstraction.
Before finishing documentation work, review the edited text as a third-party reader:
- Can the reader tell why each sentence is present?
