coding agent guidlines

.github/CLAUDE.md

@@ -8,6 +8,19 @@ Behavioral guidelines to reduce common LLM coding mistakes.
 
 **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
 
+## 0. Fast Path for Trivial Tasks
+
+**For obvious, low-risk, reversible, text only ( no source code ), single-file changes, execute directly with minimal ceremony.**
+
+- Do not create a plan, spawn or delegate to agents, run quorum review, inspect unrelated files, perform broad searches, or run Git archaeology.
+- Read only the target and, when genuinely necessary, one directly relevant instruction or nearby example.
+- Do not ask questions when the request and local convention determine the result; make the obvious reversible assumption.
+- Use the minimum tool calls: inspect, edit, and verify once. Keep progress narration to one short update at most.
+- If the preferred editing tool fails once because of an environment or tooling problem, use a safe direct fallback. Do not repeatedly debug the tool unless no safe fallback exists.
+- Verification should be proportional to the change. For a simple text edit, rereading the changed content is sufficient.
+
+This fast path overrides the planning, clarification, delegation, and quorum-review requirements below for trivial tasks. Higher-priority system, developer, safety, and explicitly invoked skill instructions still apply.
+
 ## 1. Clarify Before Executing
 
 **Resolve ambiguity up front — before spawning agents or starting any autonomous work.**
@@ -36,6 +49,10 @@ Only once these questions are resolved do you move to execution (§4).
 - No error handling for impossible scenarios.
 - If you write 200 lines and it could be 50, rewrite it.
 
+**Minimal comments**:
+
+- avoid adding code comments unless necessary (i.e. only if the code itself is not self explanatory). When necessary, code comments must be as brief as possible to ensure readability and avoid overbloating.
+
 Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
 
 ## 3. Surgical Changes
@@ -85,10 +102,7 @@ Strong, agreed-upon criteria — settled in §1 — let you loop independently.
 
 Act as an orchestrator. Fan out grunt work — reading files, gathering context, simple searches, minor mechanical edits, other simple tool calls — to cheaper agents, then review their findings and any code changes yourself before acting on them. Keep the important and dangerous work — architecture, ambiguous decisions, risky or hard-to-reverse edits, final review — on the more capable model.
 
-Which tier to spawn depends on who you are:
-
-- **If you are Fable 5**, spawn Opus 4.8 agents for grunt work that still needs some capability; for genuinely simple tasks, hand off directly to Sonnet 5 instead. Review what they return.
-- **If you are Opus 4.8**, and a task needs little knowledge or context, fan out to Sonnet 5 agents and review what they return.
+When delegation is available, use a less capable, cheaper model for genuinely simple, mechanical, low-risk work. Keep tasks requiring substantial context or judgment on the primary, more capable model.
 
 Match the model to the task: pick the cheapest tier that can do the job well, and skip an intermediate tier when the work is simple enough for a lower one.
 
@@ -98,6 +112,25 @@ Guidelines:
 - Give each agent a self-contained task with clear success criteria (per §4) so you can verify its output without redoing the work.
 - Never merge a delegated finding or edit unblocked — review it first. The cheaper model did the legwork; you own the decision.
 
+## 6. Quorum Review for Big Changes
+
+**For bigger changes, three agents check the work and two of three must agree before it counts as a success.**
+
+This applies to any change that is large, or that spans multiple files. For trivial, single-file edits, skip it and use §4's normal verification.
+
+- Spawn **three independent agents** to review the completed change, each judging against the success criteria settled in §1/§4.
+- **Vary each agent's prompt slightly so they are not identical.** Give them the same context and criteria, but frame each reviewer differently — a distinct persona or emphasis (e.g. one as a correctness-focused engineer, one probing edge cases, one checking that it actually satisfies the request). Don't hand all three the same "You are a systems engineer…" opening.
+- The change is a success only when **at least two of the three agree** it is correct and complete.
+- If the vote fails (two or more say it's wrong or incomplete), treat it as not done: address their objections, then re-run the quorum.
+- Keep their judgments independent so the vote is meaningful, and read their reasoning yourself before accepting the verdict.
+
+## 7. Reporting Results
+
+- Keep straightforward findings and small fixes in chat.
+- If a review has four or more substantive findings, or the detailed response would exceed roughly 25 lines, write the full results to a clearly named Markdown file in the repository.
+- In chat, provide only a short summary and a link to that report.
+- Do not create a report file for a simple bug, small change, or brief explanation.
+
 ## Project Overview
 
 LogExpert is a Windows log file viewer and analyzer built with C# and Windows Forms. It's a GUI replacement for the Unix `tail` command with extensive features including tail mode, filtering, bookmarks, highlighting, and a plugin-based architecture for parsing custom log formats.