# Knowledge Base Index

Tactical knowledge and patterns for AI assistants and developers.

---

## Python

### [Virtual Environments](python/virtual-environments.md)
**When to use:** Before any `pip install` command
**Key commands:** `python3 -m venv .venv && source .venv/bin/activate`
**Critical:** NEVER modify system Python

### [Type Hints](python/type-hints.md)
**When to use:** All functions require type hints
**Key patterns:** Function parameters, return types, data classes
**Critical:** Required for all organizational code

---

## Git Workflow

### [Pull Request Workflow](git/pull-request-workflow.md)
**When to use:** Every code change, no exceptions
**Key commands:** `git checkout -b feature/name`, `gh pr create`
**Critical:** NEVER push to main

### [Atomic Commits](git/atomic-commits.md)
**When to use:** Every commit - plan before coding
**Key test:** If message uses "and", split into multiple commits
**Critical:** ONE logical change per commit

### [Commit Messages](git/commit-messages.md)
**When to use:** Every git commit
**Key patterns:** `feat:`, `fix:`, `docs:`, co-authoring
**Critical:** Follow semantic commit format

---

## Testing

### [Test Structure](testing/test-structure.md)
**When to use:** Organizing tests in projects
**Key patterns:** `tests/unit/`, `tests/integration/`, fixtures
**Critical:** Mirror src/ structure

### [pytest Basics](testing/pytest-basics.md)
**When to use:** Running tests, debugging failures
**Key commands:** `pytest tests/ -v`, `pytest --cov=src`
**Critical:** Run before every commit

---

## Automation

### [Sync Tool Usage](automation/sync-tool-usage.md)
**When to use:** Syncing automation to projects
**Key commands:** `persuade sync`, `persuade sync --dry-run`, `persuade rollback`
**Critical:** Always dry-run first

### [PR Iteration](automation/pr-iteration.md)
**When to use:** Responding to PR review feedback
**Key commands:** `/iterate-pr`, automated review responses
**Critical:** Follow review-fix-push loop

---

## Claude Code

### [Permissions](claude-code/permissions.md)
**When to use:** Configuring Claude Code permissions
**Key patterns:** Wildcard syntax (`:*`), tool permissions
**Critical:** Understand allowlist vs denylist

### [Focused Prompts](claude-code/focused-prompts.md)
**When to use:** Communicating with Claude Code
**Key patterns:** Be specific, provide context, reference files
**Critical:** Clear prompts = better results

---

## Configuration as Code

### [Configuration as Code Philosophy](infrastructure/configuration-as-code.md)
**When to use:** Understanding why CaC matters in the AI age
**Key insight:** Code is context, code is text, LLMs understand text
**Critical:** Everything expressible should be code for AI collaboration

### [Infrastructure as Code Overview](infrastructure/infrastructure-as-code-overview.md)
**When to use:** Starting with IaC or understanding the complete picture
**Key concepts:** IaC workflow, environment strategy, AI-assisted management
**Critical:** Foundation document for all infrastructure work

---

## Infrastructure as Code

### Core Concepts

#### [Environment Variables](infrastructure/environment-variables.md)
**When to use:** Setting up application configuration
**Key patterns:** .env files, direnv, validation at startup
**Critical:** Never commit secrets, fail fast on missing required vars

#### [Environment Isolation](infrastructure/environment-isolation.md)
**When to use:** Setting up dev/staging/production environments
**Key concepts:** Preview deployments, data isolation, cost scaling
**Critical:** Production must be isolated from lower environments

#### [Database Migrations](infrastructure/database-migrations.md)
**When to use:** Changing database schema
**Key tools:** Supabase migrations, Alembic, Prisma
**Critical:** Migrations are code - version control, review, test

#### [Container & Compute](infrastructure/container-compute.md)
**When to use:** Choosing and configuring compute infrastructure
**Key options:** Serverless functions, edge functions, containers (Fargate)
**Critical:** Choose based on workload - start serverless, add containers when needed

#### [Storage Infrastructure](infrastructure/storage-infrastructure.md)
**When to use:** Setting up object storage, databases, caching
**Key platforms:** Cloudflare R2 (zero egress!), S3, Supabase Storage
**Critical:** R2 is ~7x cheaper than S3 for egress-heavy workloads

#### [Hybrid IaC Approaches](infrastructure/hybrid-iac-approaches.md)
**When to use:** Combining multiple infrastructure tools
**Key pattern:** justfile + Pulumi + platform CLIs (vercel, supabase, wrangler)
**Critical:** Real-world IaC combines best-in-class tools

### Financial Management

#### [Financial Governance](infrastructure/financial-governance.md)
**When to use:** Before provisioning any cloud infrastructure
**Key concepts:** Cost principles, tagging, monitoring, optimization patterns
**Critical:** ALWAYS estimate costs before deployment

#### [Cost Estimation](infrastructure/cost-estimation.md)
**When to use:** Planning infrastructure deployments
**Key tools:** Infracost, provider calculators, manual estimation
**Critical:** Include all cost components and usage levels

#### [Budget Alerts](infrastructure/budget-alerts.md)
**When to use:** Before resources go live
**Key platforms:** AWS, GCP, Azure, platform-specific monitoring
**Critical:** Set alerts at 50%, 80%, 100% of budget

#### Cost Tracking and Reporting
**When to use:** Monitoring actual costs vs. estimates

- **[Cost Tracking](infrastructure/cost-tracking.md)** - Variance detection, trend analysis, alerting
- **[Cost Dashboards](infrastructure/cost-dashboards.md)** - Visualization, CI/CD integration, reporting

**Critical:** Track actual costs to keep estimates accurate

### Pulumi Infrastructure as Code

#### [Pulumi Guide](infrastructure/pulumi-guide.md)
**When to use:** Managing infrastructure with Python
**Key features:** Resources, stacks, configuration, type safety
**Critical:** Use virtual environments, follow Python best practices

#### [Pulumi Testing](infrastructure/pulumi-testing.md)
**When to use:** Testing infrastructure code
**Key approaches:** Unit tests, integration tests, policy tests
**Critical:** Test before production deployments

#### [Pulumi Cost Controls](infrastructure/pulumi-cost-controls.md)
**When to use:** Enforcing cost policies
**Key features:** Pre-deployment checks, CrossGuard policies, auto-tagging
**Critical:** Prevent overspending through automation

### Cloud Platforms

#### [Vercel](infrastructure/vercel.md)
**When to use:** Deploying Next.js applications
**Key features:** Zero-config CDN, preview deployments, serverless functions
**Cost (as of 2025-01):** $0-20/month base, monitor bandwidth and execution

#### [Netlify](infrastructure/netlify.md)
**When to use:** JAMstack sites, static hosting
**Key features:** Forms, split testing, 25k build minutes
**Cost (as of 2025-01):** $0-19/month base, generous build minutes

#### [Cloudflare](infrastructure/cloudflare.md)
**When to use:** CDN, DNS, edge computing, object storage
**Key features:** Unlimited bandwidth, Workers, R2 (no egress fees)
**Cost:** Free tier excellent, Workers $5/month, R2 storage-only pricing

#### [Supabase](infrastructure/supabase.md)
**When to use:** PostgreSQL database with Auth and Storage
**Key features:** Row Level Security, real-time, Edge Functions
**Cost:** $0-25/month base, monitor database size and bandwidth

### Advanced Infrastructure Patterns

#### Multi-Region Deployment
**When to use:** High availability, disaster recovery, global performance

- **[Multi-Region Overview](infrastructure/multi-region-overview.md)** - Pattern comparison and decision matrix
- **[Active-Passive Pattern](infrastructure/multi-region-active-passive.md)** - DR-focused deployment
- **[Active-Active Pattern](infrastructure/multi-region-active-active.md)** - Global traffic distribution

**Critical:** Balance availability requirements with cost (2-3x increase)

#### Secrets Management
**When to use:** Managing API keys, tokens, database credentials

- **[Secrets Management](infrastructure/secrets-management.md)** - Core principles, Pulumi secrets, rotation
- **[Secrets Cloud Providers](infrastructure/secrets-cloud-providers.md)** - AWS, GCP, HashiCorp Vault

**Critical:** NEVER commit secrets to git

---

## Documentation

### [Keeping Docs Updated](documentation/keeping-docs-updated.md)
**When to use:** Every code change
**Key patterns:** Document as you code, inline + external docs, PR checklists
**Critical:** NEVER ship code without documentation

### [PR Titles and Descriptions](git/pr-titles-and-descriptions.md)
**When to use:** Every pull request
**Key patterns:** Semantic prefixes (`feat:`, `fix:`, etc.), clear "what" and "why"
**Critical:** Good descriptions accelerate reviews
## PR Feedback Guidelines (Parlant-Style)

Structured rules for reliable PR feedback classification. See `pr-feedback/README.md` for full documentation.

### [Priority Rules](pr-feedback/priority-rules.md)
**When to use:** Classifying PR feedback by severity
**Key patterns:** CRITICAL (security), HIGH (bugs), MEDIUM (standard), LOW (bots), NITPICK (style)
**Critical:** Security issues always take priority

### [Intent Detection](pr-feedback/intent-detection.md)
**When to use:** Determining what action reviewer wants
**Key patterns:** QUESTION vs CHANGE_REQUEST vs CLARIFICATION_NEEDED
**Critical:** "Why did you..." is a question, NOT a change request

### [Conflict Handling](pr-feedback/conflict-handling.md)
**When to use:** When multiple reviewers give feedback
**Key patterns:** Detect conflicts, escalate rather than guess
**Critical:** Never implement conflicting feedback - ask for clarification

### [Source Handling](pr-feedback/source-handling.md)
**When to use:** Differentiating human vs bot feedback
**Key patterns:** Human CHANGES_REQUESTED > Human COMMENTED > Bot suggestions
**Critical:** Bot feedback may have false positives

### [Self-Critique](pr-feedback/feedback-verification.md)
**When to use:** Before acting on ANY feedback item
**Key patterns:** Verify classification, check for conflicts, validate intent
**Critical:** Wrong classification = wasted iteration cycle

### [Branch Creation](pr-feedback/branch-creation.md)
**When to use:** Before creating any feature branch
**Key patterns:** ALWAYS branch from main, verify with `git branch --show-current`
**Critical:** NEVER create feature branches from other feature branches

### [PR Feedback Iteration](pr-feedback/iterate-pr-feedback.md)
**When to use:** When iterating on PR review feedback
**Key patterns:** Gather → Classify → Check Outdated → Address by Priority → Document
**Critical:** Check for outdated feedback if PR was rebased

### [Plan-First Pattern](pr-feedback/plan-first-pattern.md)
**When to use:** Before any task requiring classification or prioritization
**Key patterns:** Think (plan mode) → Approve → Act (normal mode)
**Critical:** Use `opusplan` model mode for best reasoning

---

## Quick Navigation

**By Topic:**
- **Python Setup:** [virtual-environments](python/virtual-environments.md), [type-hints](python/type-hints.md)
- **Git Operations:** [pull-request-workflow](git/pull-request-workflow.md), [atomic-commits](git/atomic-commits.md), [commit-messages](git/commit-messages.md), [pr-titles-and-descriptions](git/pr-titles-and-descriptions.md)
- **Documentation:** [keeping-docs-updated](documentation/keeping-docs-updated.md), [pr-titles-and-descriptions](git/pr-titles-and-descriptions.md)
- **Testing:** [test-structure](testing/test-structure.md), [pytest-basics](testing/pytest-basics.md)
- **Automation:** [sync-tool-usage](automation/sync-tool-usage.md), [pr-iteration](automation/pr-iteration.md)
- **Claude Code:** [permissions](claude-code/permissions.md), [focused-prompts](claude-code/focused-prompts.md)
- **Infrastructure - Cost:** [financial-governance](infrastructure/financial-governance.md), [cost-estimation](infrastructure/cost-estimation.md), [budget-alerts](infrastructure/budget-alerts.md), [cost-tracking](infrastructure/cost-tracking.md), [cost-dashboards](infrastructure/cost-dashboards.md)
- **Infrastructure - Platforms:** [vercel](infrastructure/vercel.md), [netlify](infrastructure/netlify.md), [cloudflare](infrastructure/cloudflare.md), [supabase](infrastructure/supabase.md)
- **Infrastructure - Multi-Region:** [multi-region-overview](infrastructure/multi-region-overview.md), [multi-region-active-passive](infrastructure/multi-region-active-passive.md), [multi-region-active-active](infrastructure/multi-region-active-active.md)
- **Infrastructure - Secrets:** [secrets-management](infrastructure/secrets-management.md), [secrets-cloud-providers](infrastructure/secrets-cloud-providers.md)
- **Infrastructure - Pulumi:** [pulumi-guide](infrastructure/pulumi-guide.md), [pulumi-testing](infrastructure/pulumi-testing.md), [pulumi-cost-controls](infrastructure/pulumi-cost-controls.md)
- **Configuration as Code:** [configuration-as-code](infrastructure/configuration-as-code.md), [iac-overview](infrastructure/infrastructure-as-code-overview.md)
- **Infrastructure - Core:** [environment-variables](infrastructure/environment-variables.md), [environment-isolation](infrastructure/environment-isolation.md), [database-migrations](infrastructure/database-migrations.md), [container-compute](infrastructure/container-compute.md), [storage-infrastructure](infrastructure/storage-infrastructure.md), [hybrid-iac-approaches](infrastructure/hybrid-iac-approaches.md)
- **PR Feedback:** [priority-rules](pr-feedback/priority-rules.md), [intent-detection](pr-feedback/intent-detection.md), [self-critique](pr-feedback/feedback-verification.md), [branch-creation](pr-feedback/branch-creation.md), [iterate-pr-feedback](pr-feedback/iterate-pr-feedback.md), [plan-first-pattern](pr-feedback/plan-first-pattern.md)

**By Frequency:**
- **Every Session:** [virtual-environments](python/virtual-environments.md), [pull-request-workflow](git/pull-request-workflow.md)
- **Every Commit:** [atomic-commits](git/atomic-commits.md), [commit-messages](git/commit-messages.md), [pytest-basics](testing/pytest-basics.md)
- **Before Infrastructure Changes:** [configuration-as-code](infrastructure/configuration-as-code.md), [iac-overview](infrastructure/infrastructure-as-code-overview.md), [financial-governance](infrastructure/financial-governance.md), [pulumi-guide](infrastructure/pulumi-guide.md)
- **Environment Setup:** [environment-variables](infrastructure/environment-variables.md), [environment-isolation](infrastructure/environment-isolation.md)
- **Database Changes:** [database-migrations](infrastructure/database-migrations.md)
- **Every Code Change:** [keeping-docs-updated](documentation/keeping-docs-updated.md)
- **Every PR:** [pr-titles-and-descriptions](git/pr-titles-and-descriptions.md)
- **Setup/Config:** [test-structure](testing/test-structure.md), [permissions](claude-code/permissions.md)
- **Advanced:** [sync-tool-usage](automation/sync-tool-usage.md), [pr-iteration](automation/pr-iteration.md), [hybrid-iac-approaches](infrastructure/hybrid-iac-approaches.md)

---

## Related Documentation

- **Engineering Standards:** `.claude/standards/ENGINEERING_STANDARDS.md`
- **Critical Rules:** `.claude/standards/CLAUDE_CODE_RULES.md`
- **When to Read What:** `.claude/WHEN_TO_READ.md`

---

**Status:** Knowledge base maintained by persuade template. Updated: 2026-01-15
