@northbridge-security/secureai 0.1.13

package/docs/guides/agents.markdown.md

@@ -0,0 +1,1209 @@
+# Markdown Formatting Guide for Code Agents
+
+This guide establishes formatting standards for documentation created by AI code agents. The goal is to balance scannability with detail, allowing readers to quickly understand structure while accessing implementation details when needed.
+
+## Core Principle
+
+**Readers want to see structure and concepts, not implementation details on first scan.**
+
+- Show: Headers, diagrams, short explanations, decision points
+- Hide: Code blocks, step-by-step procedures, detailed examples, lengthy lists
+
+## Technical Writing Guidelines
+
+### Emoji Usage
+
+**Problem**: AI-generated documentation often overuses emojis, creating a telltale sign of auto-generated content that undermines professionalism.
+
+**Common problematic emojis:**
+
+- ✅ Checkmark (overused for every positive statement)
+- 🔍 Magnifying glass (overused for "search" or "discover")
+- ❌ Cross mark (overused for every negative point)
+- 📊 Chart (overused for metrics or data)
+
+**Rules:**
+
+**NEVER use emojis in headers:**
+
+```markdown
+<!-- ❌ WRONG -->
+
+## ✅ Installation Guide
+
+## 🔍 Debugging
+
+## 📊 Metrics Dashboard
+```
+
+**Avoid emojis for:**
+
+- Decoration in regular text
+- Bullet point markers
+- Status indicators in lists
+- Section dividers
+- "Visual interest"
+
+**Example of excessive emoji usage (AVOID):**
+
+```markdown
+## 🎯 Getting Started
+
+✅ Install dependencies
+✅ Configure environment
+✅ Run tests
+🔍 Check the logs
+📊 View metrics
+❌ Don't forget to commit
+```
+
+**Better approach:**
+
+```markdown
+## Getting Started
+
+Prerequisites:
+
+- Install dependencies
+- Configure environment
+- Run tests
+
+Next steps:
+
+- Check logs for errors
+- Monitor metrics
+- Commit your changes
+```
+
+### Checkbox Lists
+
+**Problem**: Markdown checkbox syntax (`- [x]`, `- [ ]`) is commonly generated by AI agents and creates ambiguity about document state.
+
+**NEVER use checkbox syntax:**
+
+```markdown
+<!-- ❌ WRONG -->
+
+## Implementation Status
+
+- [x] Database schema created
+- [x] API endpoints implemented
+- [ ] Frontend components
+- [ ] Integration tests
+```
+
+**Instead, use grouped sections:**
+
+```markdown
+<!-- ✓ CORRECT - Option 1: Separate sections -->
+
+## Implementation Status
+
+### Completed
+
+- Database schema created
+- API endpoints implemented
+
+### In Progress
+
+- Frontend components
+- Integration tests
+```
+
+**Or use nested lists:**
+
+```markdown
+<!-- ✓ CORRECT - Option 2: Nested structure -->
+
+## Implementation Status
+
+**Backend (Complete)**
+
+- Database schema created
+- API endpoints implemented
+
+**Frontend (In Progress)**
+
+- Component development
+- Integration testing
+```
+
+**Or use descriptive status:**
+
+```markdown
+<!-- ✓ CORRECT - Option 3: Explicit status -->
+
+## Implementation Status
+
+- Database schema: Complete
+- API endpoints: Complete
+- Frontend components: In progress
+- Integration tests: Not started
+```
+
+### AI Adjectives and Filler Words
+
+**Problem**: AI-generated text frequently uses vague, boastful adjectives that add no meaningful information. These words are emotional rather than factual and create noise in technical documentation.
+
+**Common AI adjectives to avoid:**
+
+| Avoid            | Why                         | Use Instead                       |
+| ---------------- | --------------------------- | --------------------------------- |
+| Robust           | Vague claim                 | "Handles 10,000 requests/second"  |
+| Comprehensive    | Meaningless scope claim     | List specific features            |
+| Seamless         | Undefined integration claim | "Single-command deployment"       |
+| Cutting-edge     | Marketing speak             | Specify technology and version    |
+| Innovative       | Subjective opinion          | Describe what's different         |
+| Powerful         | Vague capability claim      | Quantify performance metrics      |
+| Advanced         | Relative and unclear        | Specify technical requirements    |
+| Efficient        | Needs quantification        | "Uses 50% less memory"            |
+| Flexible         | Vague adaptability claim    | List configuration options        |
+| Scalable         | Undefined growth claim      | "Scales to 1M users"              |
+| Revolutionary    | Hyperbolic marketing        | Describe actual improvement       |
+| State-of-the-art | Temporal and subjective     | Cite specific technology          |
+| Enterprise-grade | Meaningless qualifier       | List security/compliance features |
+| World-class      | Superlative without meaning | Use specific comparisons          |
+| Next-generation  | Vague future claim          | Specify new capabilities          |
+
+**Common AI filler phrases to avoid:**
+
+| Avoid                        | Use Instead                              |
+| ---------------------------- | ---------------------------------------- |
+| "Helps you to..."            | Direct action: "Reduces deployment time" |
+| "Allows you to easily..."    | "Deploy with one command"                |
+| "Provides the ability to..." | Direct verb: "Supports" or "Enables"     |
+| "It should be noted that..." | State directly                           |
+| "In order to..."             | "To"                                     |
+| "At this point in time"      | "Now" or "Currently"                     |
+| "Due to the fact that"       | "Because"                                |
+| "In the event that"          | "If"                                     |
+| "With regard to"             | "About" or "Regarding"                   |
+| "It is important to note"    | State directly without preamble          |
+
+**Examples of AI-typical writing:**
+
+```markdown
+<!-- ❌ WRONG - AI adjectives and filler -->
+
+Our robust and comprehensive solution provides a seamless, cutting-edge
+platform that helps you to easily manage your infrastructure. This powerful
+and innovative system allows you to efficiently deploy applications at scale.
+
+<!-- ✓ CORRECT - Specific and factual -->
+
+Deploy applications with a single command. Supports Docker and Kubernetes.
+Handles up to 100,000 concurrent connections. Deployment completes in
+under 2 minutes.
+```
+
+```markdown
+<!-- ❌ WRONG - Vague capabilities -->
+
+This advanced feature provides robust error handling and comprehensive
+logging capabilities.
+
+<!-- ✓ CORRECT - Specific features -->
+
+Retries failed requests up to 3 times with exponential backoff. Logs all
+errors to CloudWatch with stack traces. Sends alerts for 5xx errors.
+```
+
+```markdown
+<!-- ❌ WRONG - Marketing speak -->
+
+Our enterprise-grade, world-class security solution offers cutting-edge
+protection.
+
+<!-- ✓ CORRECT - Specific security features -->
+
+Security features:
+
+- AES-256 encryption at rest
+- TLS 1.3 for data in transit
+- SOC 2 Type II compliant
+- Automated vulnerability scanning
+```
+
+### Writing Style
+
+**Be direct and specific:**
+
+```markdown
+<!-- ❌ WRONG - Vague and decorated -->
+
+🎉 We've successfully implemented an amazing new feature! ✨
+
+<!-- ✓ CORRECT - Direct and specific -->
+
+Implemented real-time WebSocket notifications for user events.
+```
+
+**Replace adjectives with facts:**
+
+```markdown
+<!-- ❌ WRONG - Vague adjectives -->
+
+This comprehensive solution provides robust performance and seamless scaling.
+
+<!-- ✓ CORRECT - Quantified facts -->
+
+Processes 50,000 transactions per second. Auto-scales from 2 to 100 instances
+based on CPU usage.
+```
+
+**Eliminate filler phrases:**
+
+```markdown
+<!-- ❌ WRONG - Excessive filler -->
+
+In order to help you easily deploy your application, this tool provides the
+ability to automatically configure resources.
+
+<!-- ✓ CORRECT - Direct statement -->
+
+Automatically configures deployment resources.
+```
+
+**Use active voice:**
+
+```markdown
+<!-- ❌ WRONG - Passive voice -->
+
+The configuration file was updated and the tests were run.
+
+<!-- ✓ CORRECT - Active voice -->
+
+Updated the configuration file and ran tests.
+```
+
+### Know Your Audience
+
+**Problem**: Technical documentation often assumes all readers have the same background, native English proficiency, and technical level. This creates barriers for international teams and readers with different roles.
+
+**Key principle**: Identify your target audience and tailor content to their needs, language proficiency, and technical expertise.
+
+#### Audience Identification
+
+**Define reader roles explicitly:**
+
+```markdown
+<!-- ✓ CORRECT - Clear audience -->
+
+## Database Migration Guide
+
+**Audience**: Backend developers and database administrators
+
+**Prerequisites**:
+
+- PostgreSQL 14+ installed
+- Admin access to production database
+- Familiarity with SQL migrations
+```
+
+**Common audience types:**
+
+- **Integration engineers**: Need technical depth and step-by-step walkthroughs
+- **Operations specialists**: Need troubleshooting guides and runbooks
+- **Architects**: Need system overviews and design considerations
+- **End users**: Need simplified explanations without technical jargon
+
+#### Writing for Non-Native English Speakers
+
+Many development teams include members who do not use English as their first language. Follow these guidelines to ensure documentation is accessible:
+
+**Use simple, direct language:**
+
+```markdown
+<!-- ❌ WRONG - Complex language -->
+
+Leverage the synergistic capabilities of the system to facilitate
+seamless integration across disparate platforms.
+
+<!-- ✓ CORRECT - Simple language -->
+
+Use the API to connect different systems.
+```
+
+**Write short sentences:**
+
+```markdown
+<!-- ❌ WRONG - Long, complex sentence -->
+
+When configuring the handler, which should be done after installing
+dependencies but before running tests, ensure that the endpoint URL
+is set correctly in the configuration file.
+
+<!-- ✓ CORRECT - Short sentences -->
+
+Configure the handler after installing dependencies. Set the endpoint
+URL in the configuration file. Run tests to verify the setup.
+```
+
+**Avoid idioms and cultural references:**
+
+```markdown
+<!-- ❌ WRONG - Idioms and slang -->
+
+- This feature is a game-changer
+- Let's touch base on the deployment
+- The system went belly-up
+- We need to think outside the box
+
+<!-- ✓ CORRECT - Direct language -->
+
+- This feature improves performance by 50%
+- Schedule a deployment review meeting
+- The system crashed
+- Consider alternative approaches
+```
+
+**Avoid business jargon:**
+
+```markdown
+<!-- ❌ WRONG - Business jargon -->
+
+- Circle back
+- Low-hanging fruit
+- Move the needle
+- Synergy
+- Paradigm shift
+- Deep dive
+- Take offline
+
+<!-- ✓ CORRECT - Clear alternatives -->
+
+- Follow up
+- Quick wins
+- Make progress
+- Integration
+- Major change
+- Detailed analysis
+- Discuss separately
+```
+
+**Define abbreviations on first use:**
+
+```markdown
+<!-- ❌ WRONG - Undefined acronyms -->
+
+Configure the CDN, IAM, and VPC before deploying to ECS.
+
+<!-- ✓ CORRECT - Defined acronyms -->
+
+Configure the CDN (Content Delivery Network), IAM (Identity and Access
+Management), and VPC (Virtual Private Cloud) before deploying to ECS
+(Elastic Container Service).
+
+Subsequent references can use the acronym: "Update the IAM policies..."
+```
+
+**Use consistent terminology:**
+
+```markdown
+<!-- ❌ WRONG - Inconsistent terms -->
+
+1. Open the configuration file
+2. Edit the config
+3. Save the settings file
+4. Close the configuration
+
+<!-- ✓ CORRECT - Consistent terms -->
+
+1. Open the configuration file
+2. Edit the configuration file
+3. Save the configuration file
+4. Close the configuration file
+```
+
+#### Use Examples to Clarify
+
+**Provide concrete examples:**
+
+````markdown
+<!-- ❌ WRONG - Abstract instruction -->
+
+Ensure handlers are compatible with organizational standards.
+
+<!-- ✓ CORRECT - Concrete example -->
+
+Use the AVRO schema format for all message handlers:
+
+```json
+{
+  "type": "record",
+  "name": "UserEvent",
+  "fields": [
+    { "name": "userId", "type": "string" },
+    { "name": "timestamp", "type": "long" }
+  ]
+}
+```
+````
+
+**Show before and after:**
+
+````markdown
+<!-- ✓ CORRECT - Before/after example -->
+
+## Migrating from REST to GraphQL
+
+**Before (REST):**
+
+```text
+GET /api/users/123
+GET /api/users/123/posts
+GET /api/users/123/comments
+```
+````
+
+**After (GraphQL):**
+
+```graphql
+query {
+  user(id: 123) {
+    name
+    posts {
+      title
+    }
+    comments {
+      text
+    }
+  }
+}
+```
+
+#### Visual Aids
+
+**Use diagrams for complex concepts:**
+
+```markdown
+## System Architecture
+
+``​`mermaid
+graph LR
+    A[Client] --> B[API Gateway]
+    B --> C[Lambda Function]
+    C --> D[Database]
+``​`
+
+The client sends requests to the API Gateway. The gateway routes requests
+to Lambda functions. Lambda functions query the database.
+```
+
+**Use tables for comparisons:**
+
+| Feature    | Option A          | Option B             |
+| ---------- | ----------------- | -------------------- |
+| Speed      | Fast (< 100ms)    | Moderate (200-500ms) |
+| Cost       | High ($500/month) | Low ($50/month)      |
+| Complexity | Simple            | Complex              |
+
+**Use numbered lists for sequences:**
+
+```markdown
+## Deployment Process
+
+1. Run tests: `npm test`
+2. Build application: `npm run build`
+3. Deploy to staging: `npm run deploy:staging`
+4. Verify deployment: Check staging URL
+5. Deploy to production: `npm run deploy:prod`
+```
+
+#### Structure by Priority
+
+**Start with context, then action:**
+
+```markdown
+<!-- ✓ CORRECT - Context then action -->
+
+## Database Backup
+
+**Context**: Daily backups protect against data loss. Backups are stored
+for 30 days.
+
+**Your responsibility**: Verify backups complete successfully each day.
+
+**Steps**:
+
+1. Open monitoring dashboard
+2. Check backup status
+3. Review error logs if backup failed
+```
+
+**Put critical information first:**
+
+```markdown
+<!-- ✓ CORRECT - Critical info first -->
+
+## Security Alert
+
+⚠️ **Critical**: This endpoint requires authentication. Requests without
+valid tokens will be rejected.
+
+**Setup**:
+
+1. Generate API token in dashboard
+2. Add token to request headers
+3. Test with curl command
+```
+
+#### Action-Oriented Instructions
+
+**Use imperative verbs:**
+
+```markdown
+<!-- ❌ WRONG - Passive and vague -->
+
+The configuration file should be opened and the API endpoint field
+needs to be set to the target URL.
+
+<!-- ✓ CORRECT - Active and specific -->
+
+1. Open `config.json`
+2. Set `API_ENDPOINT` to your target URL
+3. Save the file
+4. Restart the service
+```
+
+**Break down complex tasks:**
+
+```markdown
+## Configure Database Connection
+
+**Simple task (keep together):**
+
+1. Open `.env` file
+2. Add `DATABASE_URL=postgresql://localhost:5432/mydb`
+3. Save file
+
+**Complex task (break into subtasks):**
+
+### Step 1: Generate SSL Certificates
+
+<details>
+<summary><strong>Certificate generation instructions</strong></summary>
+
+1. Install OpenSSL
+2. Generate private key: `openssl genrsa -out private.key 2048`
+3. Create certificate request: `openssl req -new -key private.key -out cert.csr`
+
+</details>
+
+### Step 2: Configure SSL in Database
+
+<details>
+<summary><strong>Database SSL configuration</strong></summary>
+
+1. Copy certificate to database server
+2. Update postgresql.conf
+3. Restart PostgreSQL
+
+</details>
+```
+
+## When to Use Collapsible Sections
+
+### DO Collapse (Use `<details>/<summary>`)
+
+**Code blocks with 10+ lines:**
+
+````markdown
+<details>
+<summary><strong>Example: Database Connection Setup</strong></summary>
+
+```typescript
+// 15+ lines of code
+const connection = createConnection({
+  host: "localhost",
+  // ... many more lines
+});
+```
+
+</details>
+````
+
+**Step-by-step procedures:**
+
+```markdown
+<details>
+<summary><strong>Step 1: Deploy Infrastructure</strong></summary>
+
+1. Configure AWS credentials
+2. Run deployment command
+3. Verify resources created
+4. Check CloudWatch logs
+
+</details>
+```
+
+**Operational runbooks:**
+
+```markdown
+<details>
+<summary><strong>Troubleshooting: Connection Timeout</strong></summary>
+
+**Problem**: Database connection times out
+
+**Solution**:
+
+1. Check security group rules
+2. Verify bastion tunnel is running
+3. Test network connectivity
+4. Review CloudWatch logs
+
+</details>
+```
+
+**Optional/reference material:**
+
+```markdown
+<details>
+<summary><strong>Advanced Configuration Options</strong></summary>
+
+For advanced users, additional configuration is available...
+
+</details>
+```
+
+**Long lists (10+ items with descriptions):**
+
+```markdown
+<details>
+<summary><strong>Available Environment Variables</strong></summary>
+
+- `DATABASE_URL` - PostgreSQL connection string
+- `REDIS_URL` - Redis connection string
+- ... (8+ more items)
+
+</details>
+```
+
+**Nested subsections with multiple code examples:**
+
+```markdown
+### Configuration Options
+
+<details>
+<summary><strong>Local Development</strong></summary>
+
+Configuration for local development environment...
+
+</details>
+
+<details>
+<summary><strong>Production Deployment</strong></summary>
+
+Configuration for production environment...
+
+</details>
+```
+
+### DO NOT Collapse (Keep Visible)
+
+**Short lists (2-5 items):**
+
+```markdown
+**Prerequisites:**
+
+- Valid AWS credentials
+- Node.js 18+
+- Bun installed
+```
+
+**Main narrative content:**
+
+```markdown
+## Overview
+
+This system provides real-time data replication from PostgreSQL to Redshift
+using AWS DMS. The architecture supports both full-load and CDC modes.
+```
+
+**Simple definitions:**
+
+```markdown
+**IQ Tests (Installation Qualification)**: Verify deployed resources match configuration
+**OQ Tests (Operational Qualification)**: Verify resources operate correctly
+```
+
+**Headers with no content:**
+
+```markdown
+## Architecture
+
+<!-- Don't wrap headers alone in details tags -->
+```
+
+**Tables:**
+
+```markdown
+| Metric | Target | Current |
+| ------ | ------ | ------- |
+| Uptime | 99.9%  | 99.95%  |
+```
+
+**Diagrams and images:**
+
+```markdown
+## System Architecture
+
+``​`mermaid
+graph TD
+    A[Source] --> B[DMS]
+    B --> C[Target]
+``​`
+
+<!-- Keep diagrams visible for quick reference -->
+```
+
+**Short code examples (< 10 lines):**
+
+```markdown
+**Quick start:**
+
+``​`bash
+bun install
+bun test
+``​`
+```
+
+## Formatting Patterns
+
+### Test Documentation
+
+```markdown
+## Test Strategy
+
+### When to Run Tests
+
+<details>
+<summary><strong>Unit Tests (<code>bun run test:unit</code>)</strong></summary>
+
+- **Run:** Always
+- **Prerequisites:** None
+- **Duration:** < 5 seconds
+
+</details>
+
+<details>
+<summary><strong>Integration Tests (<code>bun run test:integration</code>)</strong></summary>
+
+- **Run:** After infrastructure changes
+- **Prerequisites:**
+  1. Valid AWS credentials
+  2. Bastion tunnel running
+  3. Deployed infrastructure
+
+</details>
+```
+
+### Step-by-Step Workflows
+
+````markdown
+## Deployment Workflow
+
+<details>
+<summary><strong>Step 1: Prepare Environment</strong></summary>
+
+Configure your environment:
+
+```bash
+aws sso login --profile company-dev
+export AWS_PROFILE=company-dev
+```
+
+Verify credentials:
+
+```bash
+aws sts get-caller-identity
+```
+
+</details>
+
+<details>
+<summary><strong>Step 2: Deploy Infrastructure</strong></summary>
+
+Run deployment:
+
+```bash
+bun sst deploy
+```
+
+Expected output:
+
+```text
+✓ Resources created
+✓ Stack deployed successfully
+```
+
+</details>
+````
+
+### Configuration Documentation
+
+````markdown
+## Configuration
+
+### Environment Variables
+
+<details>
+<summary><strong>Required Variables</strong></summary>
+
+```bash
+DATABASE_URL=postgresql://...
+REDIS_URL=redis://...
+API_KEY=...
+```
+
+</details>
+
+<details>
+<summary><strong>Optional Variables</strong></summary>
+
+```bash
+LOG_LEVEL=debug
+ENABLE_METRICS=true
+```
+
+</details>
+````
+
+### Troubleshooting Sections
+
+```markdown
+## Troubleshooting
+
+<details>
+<summary><strong>Connection Timeout</strong></summary>
+
+**Problem**: Database connection times out after 30 seconds
+
+**Cause**: Security group rules blocking traffic
+
+**Solution**:
+
+1. Check security group ingress rules
+2. Verify bastion tunnel is running
+3. Test connectivity with netcat
+
+</details>
+```
+
+### API/Code Reference
+
+````markdown
+## API Reference
+
+### Authentication
+
+<details>
+<summary><strong><code>POST /auth/login</code></strong></summary>
+
+**Request:**
+
+```json
+{
+  "username": "user",
+  "password": "pass"
+}
+```
+
+**Response:**
+
+```json
+{
+  "token": "jwt-token",
+  "expires": "2024-01-01T00:00:00Z"
+}
+```
+
+</details>
+````
+
+## Best Practices
+
+### Summary Text
+
+**Good (active, descriptive):**
+
+```markdown
+<summary><strong>Step 3: Run Integration Tests</strong></summary>
+<summary><strong>Example: Deploy to Production</strong></summary>
+<summary><strong>Troubleshooting: Connection Refused</strong></summary>
+```
+
+**Bad (vague, generic):**
+
+```markdown
+<summary>More information</summary>
+<summary>Click here</summary>
+<summary>Details</summary>
+```
+
+### Nesting Details
+
+**Acceptable nesting (2 levels):**
+
+```markdown
+<details>
+<summary><strong>Step 1: Deploy Infrastructure</strong></summary>
+
+Main step content...
+
+<details>
+<summary><strong>Example: AWS CLI Command</strong></summary>
+
+Nested example...
+
+</details>
+
+</details>
+```
+
+**Avoid deep nesting (3+ levels)** - restructure instead.
+
+### Code Highlighting
+
+Use inline `code` for:
+
+- Commands: `bun run test`
+- File names: `config.ts`
+- Environment variables: `DATABASE_URL`
+- Function names: `connectToDatabase()`
+
+Use code blocks for:
+
+- Multi-line commands
+- Configuration files
+- Code examples
+- Output/logs
+
+### Semantic HTML
+
+**Strong emphasis:**
+
+```markdown
+<summary><strong>Important Section</strong></summary>
+```
+
+**Code in headers:**
+
+```markdown
+<summary><strong>Unit Tests (<code>bun run test:unit</code>)</strong></summary>
+```
+
+## Common Mistakes
+
+### ❌ Collapsing Everything
+
+```markdown
+<details>
+<summary>Overview</summary>
+This is a data pipeline.
+</details>
+
+<details>
+<summary>Features</summary>
+- Real-time replication
+- Automatic failover
+</details>
+```
+
+**Why wrong**: Hides essential information that should be immediately visible.
+
+### ❌ Not Collapsing Long Code
+
+```markdown
+## Configuration
+
+``​`json
+{
+  "database": {
+    "host": "localhost",
+    "port": 5432,
+    // ... 50+ more lines
+  }
+}
+``​`
+```
+
+**Why wrong**: Forces reader to scroll past implementation details.
+
+### ❌ Vague Summary Text
+
+```markdown
+<details>
+<summary>More info</summary>
+Details about the thing...
+</details>
+```
+
+**Why wrong**: Reader doesn't know what's inside without expanding.
+
+### ❌ Collapsing Tables
+
+```markdown
+<details>
+<summary>Metrics Table</summary>
+
+| Metric | Value |
+| ------ | ----- |
+| Speed  | Fast  |
+
+</details>
+```
+
+**Why wrong**: Tables are meant to be scanned quickly.
+
+## Testing Your Documentation
+
+Ask these questions:
+
+1. **Can I understand the structure without expanding anything?**
+   - If no: Collapse less, show more headers/summaries
+
+2. **Do I have to scroll past 20+ lines of code to reach the next section?**
+   - If yes: Collapse the code block
+
+3. **Are there step-by-step procedures visible on first read?**
+   - If yes: Collapse each step
+
+4. **Can I see diagrams and images immediately?**
+   - If no: Remove details tags around visuals
+
+5. **Are there 10+ list items in a row?**
+   - If yes: Consider collapsing with descriptive summary
+
+## Template: QA Documentation
+
+````markdown
+# Quality Assurance Process
+
+## Overview
+
+Brief description of QA process and philosophy. Keep visible.
+
+## Test Strategy
+
+### When to Run Tests
+
+<details>
+<summary><strong>Unit Tests (<code>bun run test:unit</code>)</strong></summary>
+
+- **Run:** Always
+- **Prerequisites:** None
+- **Duration:** < 5 seconds
+
+</details>
+
+<details>
+<summary><strong>Integration Tests (<code>bun run test:integration</code>)</strong></summary>
+
+- **Run:** After infrastructure changes
+- **Prerequisites:**
+  1. Valid credentials
+  2. Deployed infrastructure
+
+</details>
+
+### Workflows
+
+<details>
+<summary><strong>Daily Development</strong></summary>
+
+```bash
+bun run test:unit
+bun run typecheck
+bun run check
+```
+````
+
+</details>
+
+<details>
+<summary><strong>Pre-PR Validation</strong></summary>
+
+```bash
+bun run test:unit
+bun run test:integration
+```
+
+</details>
+
+## Test Execution
+
+<details>
+<summary><strong>Local Development</strong></summary>
+
+### Prerequisites
+
+```bash
+aws sso login
+export AWS_PROFILE=dev
+```
+
+### Commands
+
+```bash
+bun test
+```
+
+</details>
+
+## Troubleshooting
+
+<details>
+<summary><strong>Connection Timeout</strong></summary>
+
+**Problem**: Tests time out
+
+**Solution**:
+
+1. Check credentials
+2. Verify network access
+
+</details>
+
+## Summary
+
+**Golden rule**: Show structure and concepts, hide implementation and procedures.
+
+**Formatting decisions:**
+
+Always collapse:
+
+- Code blocks (10+ lines)
+- Step-by-step procedures
+- Optional/advanced content
+
+Always keep visible:
+
+- Diagrams and images
+- Short lists (less than 10 items)
+- Main narrative content
+- Tables and metrics
+
+Best practices:
+
+- Use descriptive summary text
+- Avoid deep nesting (max 2 levels)
+- No emojis in headers or as decoration
+- No checkbox lists - use grouped sections instead
+- Write in active voice with specific details
+- Avoid AI adjectives (robust, comprehensive, seamless)
+- Replace vague claims with quantified facts
+- Eliminate filler phrases ("helps you to", "allows you to")
+
+Audience awareness:
+
+- Identify target reader roles explicitly
+- Use simple language for non-native English speakers
+- Write short, clear sentences
+- Avoid idioms, slang, and business jargon
+- Define abbreviations on first use
+- Maintain consistent terminology throughout
+- Provide concrete examples and visual aids
+- Structure content by priority (context before action)
+
+**Result**: Documentation that's scannable on first read, with details available when needed.