From 996233c66370587dac467f32c8677357efe25d89 Mon Sep 17 00:00:00 2001 From: Julian lechner Date: Thu, 1 Oct 2026 10:22:50 +0200 Subject: [PATCH] docs(rules): unify documentation update rule Update directly affected documentation and comments; add other documentation only for a concrete need. The implementer and definition of done now defer to the general rule instead of requiring explicit approval. Co-Authored-By: Claude Opus 5.5 --- shared/agents/implementer/instructions.md | 2 +- shared/rules/definition-of-done.md | 2 +- shared/rules/general.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/shared/agents/implementer/instructions.md b/shared/agents/implementer/instructions.md index 4378a87..402a083 100644 --- a/shared/agents/implementer/instructions.md +++ b/shared/agents/implementer/instructions.md @@ -1,5 +1,5 @@ # Implementer -Understand requirements and existing code, implement the smallest complete solution, follow applicable rules, and choose proportionate verification. Inspect your changes to the degree needed for their risk; a separate or full review is not automatic. Preserve unrelated user work. Do not add comments or documentation without explicit user approval. +Understand requirements and existing code, implement the smallest complete solution, follow applicable rules, and choose proportionate verification. Inspect your changes to the degree needed for their risk; a separate or full review is not automatic. Preserve unrelated user work. Stay within assigned ownership, start at supplied references, and inspect additional context only when needed. Return changes, evidence, and unresolved risks using the shared orchestration handoff protocol; the parent owns shared task state. diff --git a/shared/rules/definition-of-done.md b/shared/rules/definition-of-done.md index 61f4e6a..6082a00 100644 --- a/shared/rules/definition-of-done.md +++ b/shared/rules/definition-of-done.md @@ -15,7 +15,7 @@ A task is only considered done when all applicable requirements below are fulfil * No temporary code, debug output, commented-out code, placeholders, or TODOs remain unless explicitly intended. * Error handling and edge cases are handled appropriately. * The implementation is readable, maintainable, and production-ready. -* Documentation and comments follow `general.md`'s Documentation and Comments rules (not changed automatically, none created without explicit instruction). +* Directly affected documentation and comments are updated; other documentation or comments are added only for a concrete need. * Any delegated research, review, or verification is complete and its relevant findings are resolved or reported. ## Work Items diff --git a/shared/rules/general.md b/shared/rules/general.md index 2f3a1fe..e5cfb1d 100644 --- a/shared/rules/general.md +++ b/shared/rules/general.md @@ -4,10 +4,10 @@ Apply instructions in this order: direct user instructions; security and data-lo Preserve security, data, compatibility, and unrelated user work. Ask only when behavior, contracts, permissions, or irreversible choices are materially ambiguous. Otherwise choose the smallest reversible change. -Use one applicable workflow per task. Treat skills and plugins as guidance subordinate to these rules. Continue work already authorized by the user; additional design approvals, documentation, commits, or delegation require a task-specific reason and the necessary authorization. +Use one applicable workflow per task. Treat skills and plugins as guidance subordinate to these rules. Continue work already authorized by the user; additional design approvals, commits, or delegation require a task-specific reason and the necessary authorization. Start repository discovery with direct reads and `rg` for known paths, symbols, exact strings, localized changes, configuration edits, and routine checks. Use the installed semantic retrieval CLI only when terminology is unknown, the question spans multiple components, or direct search did not locate the relevant flow: `python ~/.my-ai-configuration/semantic-retrieval/server.py search --root . --data-dir ~/.my-ai-configuration/semantic-retrieval/data --model-cache ~/.my-ai-configuration/semantic-retrieval/model-cache --query "..." --top-k 5`. Each uncached search uses Qwen3-Embedding-0.6B for candidate retrieval and Qwen3-Reranker-0.6B for final ranking; reuse the cache for repeated unchanged queries and verify results against current files. If Qwen is unavailable, fails, or returns no useful matches, continue with direct search and briefly report the limitation. Verify proportionally: run the cheapest check that detects likely failure; broaden for security, data loss, integration, or cross-component risk. Never claim unrun checks passed. Report failures and material gaps. -Do not create documentation or explanatory comments without a clear need. Update existing documentation or comments only when directly affected by an API, configuration, or behavior change and necessary to keep them accurate. Write repository content and user-facing output in English. +Update documentation and comments directly affected by an API, configuration, or behavior change so they stay accurate. Add other documentation or explanatory comments only for a concrete need, such as a non-obvious decision or public contract. Write repository content and user-facing output in English.