Seth-Workflow-April-2026/rules/08-code-quality.md

Code Quality Standards

Standards for code quality, commit triggers, and pre-completion verification.

Commit Triggers

Create a commit after ANY of these:

• Completing a single feature or function
• Fixing a bug (even small ones)
• Adding or modifying tests
• Updating documentation
• Before switching to a different task
• Every 15-30 minutes of active coding (at natural breakpoints)

Immutability Principle

Always create new objects, never mutate existing ones:

WRONG:  modify(original, field, value)  -- changes original in-place
RIGHT:  update(original, field, value)  -- returns new copy with change

Immutable data prevents hidden side effects, simplifies debugging, and enables safe concurrency. Apply in all languages -- use spread operators, copy(), with methods, or equivalent.

Pre-Completion Quality Checklist

Before marking any task complete, verify:

• Code is readable with well-named variables and functions
• Functions are small (<50 lines)
• Files are focused (<800 lines)
• No deep nesting (>4 levels)
• Proper error handling at every level
• No hardcoded values (use constants or config)
• Immutable patterns used (no mutation)

Communication Style

• Be concise but informative
• Explain "why" not just "what" when making decisions
• Proactively surface potential issues or alternatives
• Ask clarifying questions when requirements are ambiguous

Task Management

Use task tracking tools for multi-step work (3+ steps):

• Create tasks before starting complex work (plan first)
• Mark tasks as in-progress when starting, completed when fully done
• Never mark completed if tests fail or implementation is partial
• Express dependencies between tasks
• Keep task subjects in imperative form ("Build chat bridge", not "Chat bridge")
• Work tasks in order of dependencies

Documentation Lookup (Token-Conscious)

Use a tiered approach to minimize token usage:

1. Existing knowledge (preferred): Common patterns, stable APIs you know well
2. Lightweight fetch: Simple lookups to official documentation
3. LLM-optimized docs: Check /llms.txt endpoints when available
4. Heavy documentation tools: Reserve for complex queries or unfamiliar libraries

Each heavy documentation query can inject 5-20k tokens. Multiple queries compound quickly.