feat(docs): enhance LLM behavior guidelines with business intent preservation in code documentation

Author: Smith

.github/copilot-instructions.md

@@ -63,6 +63,12 @@ Agent engineering policies are in `docs/agent-engineering/`:
 - Adding/editing agents or skills: follow the agent-contribution process in `CONTRIBUTING.md` (create agent file, schema, eval scenarios, register in `plans/project-context.md`).
 - Tool and agent permission grants are in `governance/` (`agent-grants.json`, `tool-grants.json`, `runtime-policy.json`, `rename-allowlist.json`). Update these when changing an agent's tool profile.
 
+## Code Documentation and Language
+- Before completing an implementation phase, review the changed code for documentation that preserves non-obvious business rules, invariants, exceptions, constraints, and decision rationale. Comments should explain **why** the behavior exists or what business condition it protects, not narrate syntax or restate the code.
+- For new or materially changed public or extensible symbols that need API documentation, use the language/ecosystem-native format and the project's existing level of detail (for example, XML documentation comments in C#, docstrings in Python, or JSDoc/TSDoc in JavaScript/TypeScript). Document contract details such as parameters, return values, side effects, and expected exceptions only where they are meaningful and consistent with nearby code.
+- Match the natural language of the nearest existing code documentation. Use this precedence: the same symbol or type, then the current file/module, then the project's primary documentation language. If no reliable convention exists, use concise English. Do not mix languages within a local documentation block or translate unrelated existing comments unless the task explicitly requires it.
+- Do not add comments by quota, boilerplate documentation for self-explanatory code, or documentation churn in untouched areas. Update stale nearby documentation only when the code change makes it inaccurate.
+
 ## Agent System
 13 agents in the ControlFlow system:
 - **Orchestration:** Orchestrator

evals/tests/prompt-behavior-contract.test.mjs

@@ -769,6 +769,45 @@ console.log('\n=== Shared Policy — Behavioral Invariants ===');
     /TRIVIAL/i.test(src) && /SMALL/i.test(src) &&
     /MEDIUM/i.test(src) && /LARGE/i.test(src)
   );
+
+  const codexShared = readFileSync(
+    join(ROOT, 'plugins', 'controlflow-shared-source', 'skills', 'controlflow-planning', 'references', 'llm-behavior-guidelines.md'),
+    'utf8'
+  );
+  const codexGenerated = readFileSync(
+    join(ROOT, 'plugins', 'controlflow-codex', 'skills', 'controlflow-planning', 'references', 'llm-behavior-guidelines.md'),
+    'utf8'
+  );
+  const claudeCode = readFileSync(
+    join(ROOT, 'plugins', 'controlflow-claude-code', 'skills', 'controlflow-plan', 'references', 'llm-behavior-guidelines.md'),
+    'utf8'
+  );
+  const documentationSurfaces = [src, codexShared, codexGenerated, claudeCode];
+
+  check(
+    'Code documentation: core, Codex, and Claude preserve business intent without narrating code',
+    documentationSurfaces.every(text =>
+      /non-obvious business\s+rules/i.test(text) &&
+      /decision\s+rationale/i.test(text) &&
+      /(do not narrate|not narrate)/i.test(text)
+    )
+  );
+  check(
+    'Code documentation: native API docs include XML example and follow nearby documentation language',
+    documentationSurfaces.every(text =>
+      /language\/ecosystem-native\s+format/i.test(text) &&
+      /XML documentation comments in\s+C#/i.test(text) &&
+      /nearest existing code\s+documentation/i.test(text) &&
+      /project's primary documentation\s+language/i.test(text)
+    )
+  );
+  check(
+    'Code documentation: no comment quotas or boilerplate for self-explanatory code',
+    documentationSurfaces.every(text =>
+      /comments by quota/i.test(text) &&
+      /boilerplate documentation for self-explanatory code/i.test(text)
+    )
+  );
 }
 
 // ──────────────────────────────────────────────

plugins/controlflow-claude-code/skills/controlflow-plan/references/llm-behavior-guidelines.md

@@ -47,6 +47,23 @@ main ControlFlow prompt set.
 - For multi-phase work, keep phase acceptance criteria and quality gates explicit.
 - Match verification strength to the completion claim, then state any residual gap.
 
+### 5. Preserve Business Intent in Code Documentation
+
+- Before completing an implementation phase, review changed code for non-obvious business
+  rules, invariants, exceptions, constraints, and decision rationale that future
+  maintainers would not recover safely from syntax alone. Explain why the behavior exists
+  or what business condition it protects; do not narrate the code.
+- For new or materially changed public or extensible symbols that need API documentation,
+  use the language/ecosystem-native format and the project's existing level of detail (for
+  example, XML documentation comments in C#, docstrings in Python, or JSDoc/TSDoc in
+  JavaScript/TypeScript).
+- Match the natural language of the nearest existing code documentation: prefer the same
+  symbol or type, then the current file/module, then the project's primary documentation
+  language. If no reliable convention exists, use concise English. Do not mix languages
+  within one local documentation block or translate unrelated comments unless requested.
+- Do not add comments by quota or boilerplate documentation for self-explanatory code.
+  Update nearby documentation only when the implementation change makes it inaccurate.
+
 ## Anti-Rationalization Table
 
 | Pattern | Required Action |
@@ -57,6 +74,7 @@ main ControlFlow prompt set.
 | Clean up adjacent code while editing nearby lines | Keep edits tied to task scope and report unrelated observations without changing them. |
 | Skip verification because a change is prompt-only or documentation-only | Run the smallest relevant check plus any workflow-required gate. |
 | Treat a narrow pass as proof of a broad claim | Match the command to the claim and state what remains unverified. |
+| Add comments to make the diff look documented | Document only non-obvious business intent or meaningful API contracts, using the nearest established documentation language and style. |
 
 ## Decision Table
 

plugins/controlflow-codex/skills/controlflow-planning/references/llm-behavior-guidelines.md

@@ -46,6 +46,13 @@ Portable ControlFlow-Codex guardrails for avoiding common LLM coding anti-patter
 - For multi-phase work, keep phase acceptance criteria and quality gates explicit.
 - Match verification strength to the completion claim, then state any residual gap.
 
+### 5. Preserve Business Intent in Code Documentation
+
+- Before completing an implementation phase, review changed code for non-obvious business rules, invariants, exceptions, constraints, and decision rationale that future maintainers would not recover safely from syntax alone. Explain why the behavior exists or what business condition it protects; do not narrate the code.
+- For new or materially changed public or extensible symbols that need API documentation, use the language/ecosystem-native format and the project's existing level of detail (for example, XML documentation comments in C#, docstrings in Python, or JSDoc/TSDoc in JavaScript/TypeScript).
+- Match the natural language of the nearest existing code documentation: prefer the same symbol or type, then the current file/module, then the project's primary documentation language. If no reliable convention exists, use concise English. Do not mix languages within one local documentation block or translate unrelated comments unless requested.
+- Do not add comments by quota or boilerplate documentation for self-explanatory code. Update nearby documentation only when the implementation change makes it inaccurate.
+
 ## Anti-Rationalization Table
 
 | Pattern | Required Action |
@@ -56,6 +63,7 @@ Portable ControlFlow-Codex guardrails for avoiding common LLM coding anti-patter
 | Clean up adjacent code while editing nearby lines | Keep edits tied to task scope and report unrelated observations without changing them. |
 | Skip verification because a change is prompt-only or documentation-only | Run the smallest relevant check plus any workflow-required gate. |
 | Treat a narrow pass as proof of a broad claim | Match the command to the claim and state what remains unverified. |
+| Add comments to make the diff look documented | Document only non-obvious business intent or meaningful API contracts, using the nearest established documentation language and style. |
 
 ## Decision Table
 

plugins/controlflow-shared-source/skills/controlflow-planning/references/llm-behavior-guidelines.md

@@ -46,6 +46,13 @@ Portable ControlFlow-Codex guardrails for avoiding common LLM coding anti-patter
 - For multi-phase work, keep phase acceptance criteria and quality gates explicit.
 - Match verification strength to the completion claim, then state any residual gap.
 
+### 5. Preserve Business Intent in Code Documentation
+
+- Before completing an implementation phase, review changed code for non-obvious business rules, invariants, exceptions, constraints, and decision rationale that future maintainers would not recover safely from syntax alone. Explain why the behavior exists or what business condition it protects; do not narrate the code.
+- For new or materially changed public or extensible symbols that need API documentation, use the language/ecosystem-native format and the project's existing level of detail (for example, XML documentation comments in C#, docstrings in Python, or JSDoc/TSDoc in JavaScript/TypeScript).
+- Match the natural language of the nearest existing code documentation: prefer the same symbol or type, then the current file/module, then the project's primary documentation language. If no reliable convention exists, use concise English. Do not mix languages within one local documentation block or translate unrelated comments unless requested.
+- Do not add comments by quota or boilerplate documentation for self-explanatory code. Update nearby documentation only when the implementation change makes it inaccurate.
+
 ## Anti-Rationalization Table
 
 | Pattern | Required Action |
@@ -56,6 +63,7 @@ Portable ControlFlow-Codex guardrails for avoiding common LLM coding anti-patter
 | Clean up adjacent code while editing nearby lines | Keep edits tied to task scope and report unrelated observations without changing them. |
 | Skip verification because a change is prompt-only or documentation-only | Run the smallest relevant check plus any workflow-required gate. |
 | Treat a narrow pass as proof of a broad claim | Match the command to the claim and state what remains unverified. |
+| Add comments to make the diff look documented | Document only non-obvious business intent or meaningful API contracts, using the nearest established documentation language and style. |
 
 ## Decision Table