Coding Guardrails

Enforce simplicity-first development and prevent complexity accumulation. This skill activates automatically during coding tasks to validate decisions against ThemeGPT's development philosophy.

Required Reading

Before any coding task, mentally reference:

• CONSTITUTION.md: Philosophical principles (Simplicity > Privacy > Accessibility)
• DIRECTIVES.md: Enforcement rules with specific limits
• doc/guard/SYNTHAI_PROJECT_ARCHAEOLOGY.md: Historical lessons on over-engineering

Complexity Budget Enforcement

Hard Limits (Block if Exceeded)

| Metric | Limit | Action | |--------|-------|--------| | Single file | 200 lines | Pause and reassess | | Feature total | 500 lines | Require architectural review | | Configuration files | 50 lines total | Justify why hard-coding fails | | Abstract classes | 0 | Require 3+ concrete implementations first | | Test files | < 50% of implementation | Review necessity |

Pre-Implementation Checklist

Before writing any code, answer:

1. Scale Check: Does this complexity match the problem scale?
2. Abstraction Check: Is there proven duplication (3+ occurrences)?
3. Pattern Check: Would this pattern be appropriate for a browser extension?
4. Configuration Check: Can this value be hard-coded instead?

If any answer suggests simpler alternatives, use them.

Anti-Pattern Recognition

Actively flag and prevent these patterns from SynthAI archaeology:

Pattern 1: Specification Inflation

Warning Signs:

• Specs describe implementation details, not outcomes
• Specification longer than estimated implementation
• Bulleted requirements spawn multiple files

Response: Rewrite to focus on outcomes only. Ask "What problem does this solve?" not "How should it be built?"

Pattern 2: Enterprise Pattern Obsession

Warning Signs:

• Circuit breakers for local tools
• Service registries for < 5 items
• Rollback managers for single-user applications
• Audit logging beyond console output

Response: Remove or justify with concrete scale requirements. Browser extensions don't need enterprise infrastructure.

Pattern 3: Premature Abstraction

Warning Signs:

• Abstract class with 1 implementation
• Interface before concrete use case
• Adapter pattern for single provider
• Factory pattern for single object type

Response: Delete abstraction. Write concrete implementation. Add abstraction only when 3+ duplications exist.

Example:

// BAD: Premature abstraction
abstract class BaseProvider {
  abstract call(input: string): Promise<string>;
}
class OpenAIProvider extends BaseProvider { ... }
// Only one provider exists!

// GOOD: Direct implementation
async function callOpenAI(input: string): Promise<string> {
  return await openai.complete(input);
}

Pattern 4: Configuration Explosion

Warning Signs:

• Config file growing beyond 50 lines
• Environment variables for internal values
• YAML/JSON for hard-codeable constants
• Configuration for "flexibility"

Response: Hard-code by default. Make configurable only when users demonstrably need to change values.

Example:

// BAD: Configuration for hard-codeable value
const config = loadConfig();
const MAX_TOKENS = config.maxTokens ?? 4096;

// GOOD: Hard-coded default
const MAX_TOKENS = 4096;

Pattern 5: Framework Absorption

Warning Signs:

• Domain-specific types in utility modules
• Framework concepts leaking into generic code
• Every module imports domain-specific types

Response: Keep domain frameworks separate. Utilities should have no domain dependencies.

Pattern 6: Test Suite Inflation

Warning Signs:

• Tests approaching implementation size
• Tests per function instead of per behavior
• High coverage on trivial code

Response: Tests < 50% of implementation lines. Test behavior, not implementation. Skip tests for trivial code (getters, simple mappings).

Decision Framework

When principles conflict, apply this priority:

1. Simplicity — Never add complexity beyond what the problem requires
2. Privacy — Never compromise user data protection
3. Accessibility — Never exclude users
4. Brand Integrity — Maintain visual consistency
5. Completeness — No placeholders or incomplete features
6. Performance — Fast, responsive extension

Verification Commands

Run these checks before committing:

# Check for files over 200 lines (warning threshold)
find apps packages -name "*.ts" -o -name "*.tsx" | xargs wc -l | awk '$1 > 200 {print "WARNING:", $0}'

# Check for placeholder content
grep -rE "TODO|FIXME|TBD|XXX|lorem ipsum" --include="*.ts" --include="*.tsx" apps/ packages/

# Check for premature abstractions
grep -rE "abstract class|interface.*Adapter|Registry|Factory" --include="*.ts" apps/ packages/

# Check config file sizes
find . -name "*.json" -o -name "*.yaml" | xargs wc -l | awk '{sum+=$1} END {print "Total config lines:", sum}'

# Check test-to-implementation ratio
echo "Test lines:" && find apps packages -name "*.test.ts" | xargs wc -l 2>/dev/null | tail -1
echo "Impl lines:" && find apps packages -name "*.ts" ! -name "*.test.ts" | xargs wc -l 2>/dev/null | tail -1

Response Protocol

When this skill activates during a coding task:

1. Before Implementation: Run pre-implementation checklist mentally
2. During Implementation: Flag any anti-pattern warning signs immediately
3. Before Committing: Run verification commands
4. If Limits Exceeded: Stop, explain the concern, propose simpler alternative

Key Phrase Triggers

Activate heightened scrutiny when you hear:

• "We might need..."
• "For flexibility..."
• "In case of..."
• "Best practice says..."
• "Enterprise-grade..."
• "Future-proof..."

These phrases often precede unnecessary complexity.

Simplicity Mantra

"Sometimes the best code is the code you don't write." — SynthAI Project Archaeology

When in doubt, implement the minimal solution. Complexity can be added later; removing it is much harder.