docs

Developer Handbook

This is the project knowledge base. It covers the conventions, workflows, and principles you need to work on gitea-mcp-server. Everything here is available directly — no skill loading required.

Documentation map: See docs/INDEX.md for the full doc set with audience, type, and topic ownership for every document.

---

Documentation philosophy

Code, comments, docstrings, tests, and the docs/ directory together form a single layered knowledge base. Through an index (docs/INDEX.md) this knowledge is navigable, making discovery straightforward.

• Documentation is as much a deliverable as code.
• A doc that says where to look is more valuable than one trying to say everything.
• Always update and improve the documentation. It makes the next job easier.

The structural policies that follow from this philosophy (audience split, de-duplication invariant, pragmatic Diátaxis) live in docs/DOCUMENTATION_STANDARDS.md.

---

RED FLAGS — STOP AND ABORT

• ✗ Starting work without reading the relevant docs/INDEX.md first to navigate the docs
• ✗ Editing files on main branch
• ✗ PR without Fixes #XX reference
• ✗ "Quick fix" that skips issue creation
• ✗ Ignoring test failures
• ✗ Launching a discovery for things already documented
• ✗ Launching a subagent for static code structure discovery (the docs already have module maps, pipeline diagrams, and data flows)

Any of these means: Abort. Create issue, create proper branch, read relevant doc, follow full workflow.

---

Invariants are executable, not prose

When you state an invariant — in a design note, a docstring, a comment — turn it into a check before you write the code. A comment does not fail; a test does. If you cannot express the invariant as a check, you do not yet understand it well enough to rely on it.

The canonical statement and its embodiments are Pattern 7 in docs/DESIGN.md.

Split at round two

A PR that needs a third review round is telling you something: it is still surfacing structural decisions, not bugs. At that point, stop iterating and split the remaining work into its own issue/PR.