From 326b026ab3bee9374cdad0975cc276a65c1ed061 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 16 Jun 2026 22:45:19 +0800
Subject: [PATCH] docs(development): document FIXME/TODO/XXX markers

Define the three issue-urgency tags so contributors can flag a release
blocker, a soon-to-fix item, and a someday-maybe consistently.
---
 docs/development.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/development.md b/docs/development.md
index 0defe20cec..d19308faa0 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -116,6 +116,16 @@ The coding-agent demo uses the real DeepSeek adapter and needs `DEEPSEEK_API_KEY
 pnpm run demo:coding
 ```
 
+## TODO markers
+
+Use one of three comment tags to flag known issues in the code, ordered by urgency:
+
+- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.
+- `TODO` — an issue that should be fixed soon, once we have the resources.
+- `XXX` — an issue that we may fix someday; lowest priority, no commitment.
+
+Pick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.
+
 ## Architecture context
 
 Read `docs/architecture.md` before changing anything under `packages/`. The codebase is built around Cordis plugins, event-sourced sessions, typed service seams, and explicit extension points.