aiwg/agentic/code/addons/writing-quality/core/sophistication-guide.md

Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.

# Maintaining Sophistication and Authority

## The Problem We're Solving

Removing AI patterns shouldn't mean dumbing down content. The goal is to eliminate performative language while
preserving intellectual depth, technical precision, and professional authority.

## What We're NOT Doing

### We're NOT Simplifying to Child-Level

❌ **Wrong**: "The computer program makes things go fast" ✅ **Right**: "The algorithm optimizes throughput using parallel
processing and cache-aware data structures"

### We're NOT Removing Technical Vocabulary

❌ **Wrong**: "We used a special database thing" ✅ **Right**: "We implemented a time-series database with columnar
storage for analytical queries"

### We're NOT Writing Like We're Texting

❌ **Wrong**: "yeah so basically the API was broken lol" ✅ **Right**: "The API failed due to malformed JWT tokens in the
authorization header"

## What We ARE Doing

### Removing Performative Enhancement

❌ **AI Pattern**: "Our cutting-edge, revolutionary platform leverages state-of-the-art technology" ✅ **Expert Voice**:
"The platform uses WebAssembly for near-native performance in browsers"

The second version is actually MORE sophisticated - it demonstrates real knowledge rather than empty adjectives.

### Eliminating Formulaic Structures

❌ **AI Pattern**: "Moreover, it is important to note that the system's comprehensive architecture..." ✅ **Expert
Voice**: "The system's event-driven architecture handles 10,000 concurrent connections through epoll on Linux"

Again, more sophisticated because it's specific and technical.

### Replacing Marketing with Expertise

❌ **AI Pattern**: "Seamlessly integrating best-in-class solutions" ✅ **Expert Voice**: "Integration via REST APIs with
fallback to GraphQL for complex queries"

## Maintaining Reading Level

### Academic/Professional Standard

Target reading level: College to Graduate level for technical content

- Complex sentence structures when explaining complex concepts
- Domain-specific terminology without apology
- Multi-clause sentences for nuanced ideas

### Example of Appropriate Complexity

> "The distributed consensus mechanism employs a modified Raft protocol with optimizations for geo-distributed clusters,
> specifically addressing the latency challenges inherent in cross-region replication while maintaining linearizability
> guarantees under partition scenarios."

This is complex because the concept is complex, not because we're trying to sound smart.

## Voice of Authority

### Demonstrate Deep Knowledge

Instead of broad claims, show specific expertise:

- Name specific technologies, protocols, algorithms
- Reference actual constraints and trade-offs
- Include version numbers, performance metrics, configuration details

### Examples of Authoritative Voice

**Distributed Systems**:
> "We chose CockroachDB over Cassandra despite the operational overhead because we needed serializable isolation for
> financial transactions. The performance hit - roughly 20% on writes - was acceptable given the consistency
> requirements."

**Machine Learning**:
> "The model uses a transformer architecture with 12 attention heads and 768-dimensional embeddings. We found that
> increasing to 24 heads provided marginal improvement (2% on F1 score) while doubling inference time, so we stayed with
> the smaller architecture."

**Security**:
> "Authentication uses OIDC with PKCE flow for SPAs, storing tokens in httpOnly cookies with SameSite=Strict to mitigate
> XSS and CSRF vectors. We considered WebAuthn but adoption rates in our user base are still below 15%."

## Sophisticated Patterns to Keep

### Technical Precision

- "The service exhibits O(n log n) complexity"
- "Implements the Circuit Breaker pattern with exponential backoff"
- "Uses Copy-on-Write semantics for thread safety"

### Professional Constructions

- "This approach, while computationally expensive, ensures data consistency"
- "Performance degrades linearly with dataset size"
- "The architecture follows Domain-Driven Design principles"

### Nuanced Assessments

- "The solution is optimal for read-heavy workloads but struggles with write amplification"
- "While theoretically sound, practical implementation revealed edge cases"
- "The abstraction leaks under high concurrency"

## Balancing Authenticity with Authority

### Include Real Challenges (Sophisticatedly)

❌ **Too Casual**: "The thing broke and we didn't know why" ✅ **Professional**: "We encountered race conditions in the
connection pool that only manifested under specific load patterns - reproduction required simulating 10,000 concurrent
connections with asymmetric request timing"

### State Opinions with Expertise

❌ **Too Simple**: "GraphQL is bad" ✅ **Authoritative**: "GraphQL's flexibility becomes a liability when clients can
construct queries that trigger N+1 database operations, effectively allowing denial-of-service through query complexity"

### Acknowledge Trade-offs Professionally

❌ **Too Casual**: "We picked the easy way because deadline" ✅ **Professional**: "Given the time constraints, we opted
for a proven solution rather than the theoretically superior but untested approach"

## Domain-Specific Expectations

### Software Engineering

- Use design pattern names
- Reference specific algorithms
- Include Big O notation
- Mention specific tools and versions

### Data Science

- Statistical terminology
- Model architectures
- Evaluation metrics
- Dataset characteristics

### DevOps/SRE

- Infrastructure as Code
- Monitoring and observability terms
- SLA/SLO/SLI references
- Specific cloud services

## Red Flags of Over-Simplification

### Lost Authority Indicators

- Reading level below 10th grade for technical content
- Avoiding technical terms that have no simple equivalent
- Single-syllable words dominating
- Lack of subordinate clauses
- No domain-specific vocabulary

### Examples of Over-Correction

❌ **Too Simple**:
> "We made a program. It runs fast. Uses less memory. Boss happy."

✅ **Appropriate Complexity**:
> "We refactored the service to use memory pooling and zero-copy techniques, reducing heap allocations by 70% and
> improving p99 latency from 200ms to 45ms."

## The Sophistication Test

Ask yourself:

1. Would a senior engineer write this?
2. Does it demonstrate deep understanding?
3. Is complexity justified by the subject matter?
4. Would peers respect this analysis?
5. Does it use the vocabulary of the domain?

## Final Principle

**Sophistication comes from precision and depth, not from fancy words or complex grammar.**

Write like someone who:

- Has deep expertise
- Can explain complex ideas clearly
- Knows when complexity is necessary
- Isn't trying to impress, just to communicate accurately

The goal is to sound like an expert explaining to other experts, not an AI trying to sound impressive or a novice trying
to sound casual.