From ac0c0cbe731f37a4854d7d5aadb86e98d5321809 Mon Sep 17 00:00:00 2001 From: conductor-tier2 Date: Tue, 9 Jun 2026 14:03:18 -0400 Subject: [PATCH] docs(styleguide): add No-Diagnostic-Noise rule to AI-Agent Conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit One addition to conductor/code_styleguides/python.md §8 "AI-Agent Specific Conventions": - **No diagnostic noise in production code (Added 2026-06-09).** `sys.stderr.write(f"[XYZ_DIAG] ...") lines in src/*.py are technical debt. The right place for one-time investigation output is tests/artifacts/.diag.log (a log file) or a standalone /tmp/diag_.py script. If you must instrument production code, the diag lines are part of the same atomic commit as the fix. - **Test files ARE allowed to be diagnostic.** The rule applies to src/*.py only; tests/test_*.py may use print(..., file=sys.stderr) freely. Markdown only. No code modified. --- conductor/code_styleguides/python.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/conductor/code_styleguides/python.md b/conductor/code_styleguides/python.md index 5982a9a5..d255ebc4 100644 --- a/conductor/code_styleguides/python.md +++ b/conductor/code_styleguides/python.md @@ -67,6 +67,8 @@ is processed by AI agents, while preserving readability for human review. - **No empty `__init__.py` files.** - **Minimal blank lines.** Token-efficient density is preferred over visual padding. - **Short variable names are acceptable** in tight scopes (loop vars, lambdas). Use descriptive names for module-level and class attributes. +- **No diagnostic noise in production code (Added 2026-06-09).** `sys.stderr.write(f"[XYZ_DIAG] ...")` lines added to `src/*.py` for one-time debugging are technical debt the moment they ship. The project's production code should not contain `[XYZ_DIAG]` markers, `print(...debug...)` calls, or any other ad-hoc debug instrumentation. The right place for diagnostic output during a one-time investigation is `tests/artifacts/.diag.log` (a log file) or a standalone `/tmp/diag_.py` script. If you must instrument a production function for a single test run, the diag lines are part of the same atomic commit as the fix — they do not live uncommitted in the working tree. If you "revert everything," that means the diag lines are also reverted. +- **Test files ARE allowed to be diagnostic.** `tests/test_*.py` may use `print(..., file=sys.stderr)` freely for test output. The rule against diagnostic noise applies to `src/*.py` only. ## 10. Anti-OOP Conventions