codebygarv/Ai-skills

## Purpose

Document an architectural decision in ADR format — capturing not just *what* was decided, but the context that forced the decision, the alternatives considered, and the consequences accepted. The value is for the reader six months later asking "why on earth is it built this way."

## When to Use

- A significant technical decision has been made and needs to be recorded.
- Onboarding docs keep having to explain the same "why is it like this" question verbally.
- Retroactively documenting an existing decision whose rationale lives only in people's heads.

Pairs with [Decision Maker](../../reasoning/decision-maker/): that skill *makes* the decision by comparing options; this skill *records* a decision in a durable, standard format.

## What to Analyze / Do

## Purpose

Review a system's architecture — how components/services are divided, how they communicate, where state lives, and how the pieces depend on each other — for scalability, coupling, and long-term maintainability, at a level above individual code review.

## When to Use

- Evaluating a proposed or existing system architecture.
- Before a significant scaling milestone, to find what will break first.
- A codebase feels hard to change, and the cause seems structural rather than isolated to one file.

## What to Analyze

1. **Separation of concerns** — are responsibilities cleanly divided (data access, business logic, presentation), or is logic scattered/duplicated across layers that shouldn't need to know about each other?
2. **Coupling** — how many places break if one component changes its interface? Tight coupling between components that should be independent is the main long-term maintainability risk.

## Purpose

Architect robust, multi-layer caching strategies (HTTP/CDN edge, distributed Redis/Memcached, in-process local memory) with explicit TTLs, cache invalidation hooks, and cache stampede (thundering herd) protections.

## When to Use

- High-read database bottlenecks or slow third-party API response times.
- Designing CDN caching rules (`Cache-Control`, `stale-while-revalidate`, surrogate keys).
- Fixing cache stampedes that crash origin servers when popular cache keys expire.

## What to Analyze

1. **Cache Tier Selection**: L1 (In-memory LRU, sub-millisecond) vs L2 (Redis Cluster, 1-2ms) vs Edge CDN (Cloudflare/Fastly).
2. **Write Strategy**: Cache-Aside (Lazy Loading), Write-Through, Write-Behind (Write-Back).

## Purpose

Audit cloud infrastructure (AWS, GCP, Azure, Kubernetes, SaaS dependencies) to uncover idle resources, over-provisioned instances, unattached disks, sub-optimal storage tiers, and high data-transfer egress costs.

## When to Use

- Monthly cloud bills are growing faster than business revenue.
- Pre-planning infrastructure budget reviews or FinOps initiatives.
- Right-sizing Kubernetes pod CPU/memory requests and limits based on actual utilization.

## What to Analyze

1. **Compute Right-Sizing**: Underutilized EC2/GCE VMs (CPU < 15%), idle dev/staging clusters, ARM (Graviton) migration.
2. **Storage Tiering & Cleanup**: Unattached EBS volumes, old disk snapshots, S3 Intelligent-Tiering and lifecycle expiration rules.

## Purpose

Architect Command Query Responsibility Segregation (CQRS) and Event Sourcing (ES) systems, separating write-side domain command handling from read-side materialized view projections with full auditability.

## When to Use

- High-compliance domains requiring immutable audit logs (Fintech, Healthcare, Legal, Supply Chain).
- Systems with asymmetric read/write ratios and complex reporting queries.
- Designing collaborative workspaces with branch/merge or time-travel history.

## What to Analyze

1. **Command vs Query Separation**: Command handlers (validate and emit events) vs Query handlers (read denormalized projections).
2. **Event Store Architecture**: Append-only immutable log (`aggregate_id`, `version`, `event_type`, `payload`) with optimistic concurrency control.

## Purpose

Formulate enterprise Disaster Recovery (DR) and Business Continuity plans, defining Recovery Time Objectives (RTO), Recovery Point Objectives (RPO), multi-region replication, and automated split-brain prevention.

## When to Use

- Preparing architecture for SOC 2, ISO 27001, or enterprise compliance audits.
- Designing active-passive (pilot light / warm standby) or active-active multi-region systems.
- Establishing automated database backup verification and restore drills.

## What to Analyze

1. **RTO & RPO Definitions**: Acceptable data loss in time (RPO) and acceptable downtime duration (RTO) per tier.
2. **Topology Strategy**: Backup & Restore vs Pilot Light vs Warm Standby vs Active-Active Multi-Region.

## Purpose

Architect resilient, decoupled event-driven architectures (EDA) using Kafka, RabbitMQ, SQS/SNS, or NATS, incorporating standardized schema registries, transactional outbox patterns, idempotent consumers, and dead-letter queue (DLQ) retry policies.

## When to Use

- Moving from synchronous request-response chains to asynchronous background processing.
- Ensuring guaranteed event delivery without dual-write inconsistency (Transactional Outbox).
- Designing event topics, partition keys for ordering, and consumer group scaling.

## What to Analyze

1. **Event Schema Design**: Standard envelopes (CloudEvents spec), event types, versioning, and payloads.
2. **Publishing Reliability**: Transactional Outbox pattern with Debezium or polling to prevent lost events if broker is down.

## Purpose

Manage feature flags from creation to deprecation, establishing standardized flag taxonomy, safe fallback defaults, phased rollout rings (canary/percentage/user groups), and automated dead-code cleanup to prevent technical debt accumulation.

## When to Use

- Introducing feature flag tooling (LaunchDarkly, Unleash, PostHog, custom Redis flags).
- Codebases clogged with hundreds of ancient, permanent boolean flags.
- Releasing risky changes using percentage rollouts and progressive ring deployments.

## What to Analyze

1. **Flag Taxonomy & Lifetime**: Release Toggle (short-lived, days) vs Experiment Toggle (weeks) vs Kill Switch (permanent) vs Permission Toggle.
2. **Safe Fallback Defaults**: Guaranteed fail-safe default value if the flag service is unreachable.

## Purpose

Plan a migration from an existing system to a new one in incremental, individually-reversible steps — so the migration can be paused, verified, or rolled back at any point, rather than being a single high-risk cutover.

## When to Use

- Migrating a framework, database, service, or platform that's already running in production.
- Replacing a component where a big-bang cutover would be too risky to attempt.
- The user asks how to "migrate," "move off," or "replace" something existing.

Differs from [Project Planner](../project-planner/): that plans building something new; this plans *replacing* something that already exists and must keep working throughout.

## What to Analyze / Do

## Purpose

Architect secure, cost-effective, and scalable database multi-tenancy models (Shared Database/Shared Schema with Row-Level Security, Database-per-Tenant, Schema-per-Tenant) tailored to compliance, isolation, and cost constraints.

## When to Use

- Designing the data architecture for a B2B SaaS application.
- Enterprise customers requesting strict physical data isolation or custom backup schedules.
- Evaluating database costs vs cross-tenant data leakage risks.

## What to Analyze

1. **Isolation Model Selection**:
   - *Shared Database, Shared Schema (Pool)*: Highest resource efficiency, lowest cost, enforced via Postgres RLS.

## Purpose

Turn an idea, feature request, or goal into a structured development plan — phases, milestones, concrete tasks, and their dependencies — so work can actually start in the right order instead of everyone improvising sequencing.

## When to Use

- An idea exists but hasn't been broken into actionable phases/tasks yet.
- Kicking off a nontrivial feature or project and want a shared plan before work starts.
- Coordinating work across multiple people/teams where task ordering and dependencies matter.

## What to Analyze / Do

1. **Clarify the goal and scope** — what does "done" look like; what's explicitly out of scope (pair with [Requirements Extractor](../../reasoning/requirements-extractor/) if the goal itself is still vague).
2. **Break into phases** — logical stages of work where each phase produces something usable or verifiable, not arbitrary time-boxed chunks.

## Purpose

Architect scalable, distributed rate limiting and traffic throttling systems using Token Bucket, Leaky Bucket, Sliding Window Log, or Sliding Window Counter algorithms to protect APIs from abuse and noisy neighbors.

## When to Use

- Protecting public APIs from DDoS, credential stuffing, and scraping.
- Implementing multi-tier usage limits (Free vs Pro vs Enterprise quotas).
- Managing outbound rate limits to comply with third-party vendor quotas (OpenAI, Stripe).

## What to Analyze

1. **Algorithm Selection**: Token Bucket (bursts allowed) vs Leaky Bucket (smooth pacing) vs Sliding Window Counter (memory efficient).
2. **Identification Key**: User ID, Organization ID, API Token, or IP address (with X-Forwarded-For trust validation).

## Purpose

Turn a vague sense that "the codebase has a lot of debt" into a ranked, justified paydown list — assessing each item by what it actually costs to keep living with it, versus what it costs to fix.

## When to Use

- Technical debt is accumulating and it's unclear what to tackle first.
- Justifying debt-paydown work to stakeholders who need a reason beyond "it's messy."
- Planning a cleanup sprint and needing to pick the highest-value targets.

Differs from [Refactor Expert](../../development/refactor-expert/): that skill simplifies one specific piece of code; this one operates at portfolio level across the codebase, deciding *what* is worth refactoring at all.

## What to Analyze

## Purpose

Formulate zero-downtime deployment and database migration blueprints (Expand/Contract pattern, Parallel Run, Blue-Green, Canary) allowing continuous availability during breaking changes.

## When to Use

- Renaming or splitting database columns in high-traffic tables.
- Replacing a core microservice or authentication provider without maintenance windows.
- Executing major database engine upgrades with replication cutovers.

## What to Analyze

1. **Expand & Contract Phases**:
   - *Phase 1 (Expand)*: Add new nullable column/table alongside old one.

## Purpose

Design or review REST API surfaces — routes, resource modeling, request/response shapes, status codes, versioning, and error formats — so the API is consistent, predictable, and follows established conventions rather than ad hoc choices per endpoint.

## When to Use

- Designing new endpoints or a new API from scratch.
- Reviewing an existing API for consistency before it gets more consumers.
- The user has a rough idea of what an endpoint should do and needs it shaped into a proper REST contract.

## What to Analyze / Do

1. **Resource modeling** — identify the actual resources and their relationships; prefer nouns-as-resources over RPC-style action endpoints where REST conventions fit naturally.
2. **Route design** — consistent pluralization, nesting depth (avoid over-nesting past 2 levels), and clear path parameters.

## Purpose

Hunt specifically for defects — not style, not maintainability, not architecture. The single question driving this skill is: "under what real input or timing, does this code produce a wrong result or crash?"

## When to Use

- The user wants bugs found, specifically — not a general quality review.
- Before shipping code that handles money, user data, or concurrency, where a missed bug is expensive.
- Debugging: the user suspects a bug exists somewhere in a file/module but hasn't found it yet.

## What to Analyze

1. **Boundary conditions** — empty collections, zero, negative numbers, max values, single-element cases.
2. **Null/undefined/missing data** — every place data is accessed, ask what happens if it's absent.

## Purpose

Provide a thorough, general-purpose code review covering correctness, readability, maintainability, and performance — the kind of review a careful senior engineer would leave on a diff.

## When to Use

- Reviewing a diff, PR, file, or function before merge.
- The user asks for "a code review" without narrowing to a specific concern (security, types, performance) — those narrower concerns have their own skills ([Security Auditor](../security-auditor/), [TypeScript Guardian](../typescript-guardian/), [Performance Auditor](../performance-auditor/)) and this skill should defer to them for deep dives in those areas while still flagging obvious issues.

## What to Analyze

1. **Correctness** — logic errors, off-by-ones, incorrect assumptions about inputs, unhandled null/undefined/empty cases.
2. **Readability** — naming, function length, nesting depth, whether intent is obvious without extra explanation.
3. **Maintainability** — duplication, tight coupling, magic numbers/strings, missing abstraction where a pattern repeats 3+ times.

## Purpose

Detect and resolve concurrency vulnerabilities, shared-state data races, asynchronous interleaving bugs, lock inversion deadlocks, and missed synchronization in multi-threaded or async event-loop environments.

## When to Use

- When debugging intermittent bugs that only reproduce under high concurrency or specific network latency.
- Reviewing shared in-memory caches, counter updates, or distributed lock implementations.
- Writing Go goroutines, Rust async/tokio, Java threads, or Node.js async operations with shared references.

## What to Analyze

1. **Shared Mutable State**: Find variables, collections, or files accessed concurrently without atomics or locks.
2. **Check-Then-Act Flaws (TOCTOU)**: Inspect code where state is checked, and acted upon in separate non-atomic operations.

## Purpose

Review or design database schemas for correctness (data integrity is actually enforced, not just assumed), scalability (queries stay fast as data grows), and sound relational/data modeling.

## When to Use

- Designing a new schema or table structure.
- Reviewing an existing schema before it grows harder to change.
- Diagnosing why queries are slow, and the cause looks like a modeling/indexing issue.

## What to Analyze / Do

1. **Normalization vs. denormalization** — is data duplicated in a way that risks inconsistency, or normalized past the point of being queryable without excessive joins? Neither extreme is automatically correct — judge against actual access patterns.
2. **Relationships & foreign keys** — are relationships modeled correctly (1:1, 1:many, many:many via join table), and are foreign key constraints actually declared, not just implied by naming?

## Purpose

Review a project's dependency manifest for bloat, risk, and duplication — packages that shouldn't be there, packages that duplicate functionality, and packages that carry maintenance or licensing risk.

## When to Use

- The dependency list has grown over time without anyone auditing it.
- Before adding a new dependency, to check if an existing one already covers the need.
- Investigating bundle size or install time bloat.

## What to Analyze

1. **Unnecessary packages** — dependencies for functionality that's a few lines of code, or that duplicate a built-in language/runtime feature.
2. **Duplication** — multiple packages solving the same problem (e.g. two date libraries, two HTTP clients) introduced at different times by different people.

## Purpose

Standardize application error handling into a coherent architecture: custom error hierarchies, typed domain errors, HTTP/RPC status mappings, sanitized client responses, and structured observability logs.

## When to Use

- When error handling is fragmented with ad-hoc `try/catch` blocks, string checks, or unhandled promise rejections.
- Designing error responses for public REST/gRPC APIs.
- Setting up retry policies, circuit breakers, and graceful fallback behaviors.

## What to Analyze

1. **Error Hierarchy**: Base domain error, validation errors, not found errors, authorization errors, external service errors.
2. **Transport Mapping**: Clean translation from internal domain error classes to HTTP status codes / RFC 7807 Problem Details.

## Purpose

Design clean, evolvable, and performant GraphQL schemas following best practices for naming, mutations, connection pagination, error modeling, and batch resolution (DataLoader).

## When to Use

- Designing new GraphQL types, queries, and mutations.
- Refactoring sprawling, unprincipled GraphQL schemas.
- Preventing N+1 database queries and performance bottlenecks in nested resolvers.

## What to Analyze

1. **Schema Design & Naming**: Verb-noun conventions for mutations, scalar types, and deprecation strategies.
2. **Pagination Pattern**: Relay Cursor Connections (`first`, `after`, `edges`, `node`, `pageInfo`).

## Purpose

Plan safe, incremental refactorings of complex, untested legacy codebases using proven methodologies (Mikado Method, Characterization Testing, Strangler Fig pattern, Seams) without breaking production behavior.

## When to Use

- Refactoring sprawling 3,000-line "God classes" or legacy spaghetti functions.
- Untangling deeply coupled monolithic code with zero existing unit tests.
- Modernizing ancient callback-hell or global-state architectures into clean, testable interfaces.

## What to Analyze

1. **Characterization Tests (Golden Master)**: Capture existing behavior with black-box snapshot tests before touching code.
2. **Mikado Graph**: Map dependency prerequisites to identify leaf nodes that can be refactored safely first.

## Purpose

Detect and fix memory leaks, lingering closures, detached DOM trees, unbounded cache growth, and uncollected resources in Node.js, JavaScript, Python, Go, and mobile applications.

## When to Use

- Applications whose memory (RSS / Heap) steadily climbs until crashing with Out-Of-Memory (OOM) errors.
- Investigating heap profile snapshots and GC thrashing.
- Reviewing caching layers, WebSocket connection registries, and event listeners.

## What to Analyze

1. **Unbounded In-Memory Collections**: Global arrays/maps that append data without TTL, LRU eviction, or size caps.
2. **Lingering Event Listeners / Subscriptions**: Attaching listeners on recurring objects without matching `removeEventListener` / `unsubscribe`.

## Purpose

Define high-cohesion, low-coupling service boundaries using Domain-Driven Design (DDD) strategic design principles, avoiding distributed monolith anti-patterns and chatty network coupling.

## When to Use

- Planning the extraction of services from a monolithic codebase.
- Splitting a team or scaling engineering throughput across organizational boundaries (Conway's Law).
- Correcting overly granular nanoservices that require distributed transactions.

## What to Analyze

1. **Domain Entities & Aggregates**: Group data that must maintain transactional consistency within a single boundary.
2. **Ubiquitous Language**: Identify terms that mean different things in different contexts (e.g. `Account` in Billing vs `Account` in Auth).

## Purpose

Identify concrete performance bottlenecks across the stack — frontend, backend, database, network — and quantify their likely impact, rather than offering generic "make it faster" advice.

## When to Use

- Something is measurably slow and the cause isn't obvious.
- Reviewing code before it needs to handle significantly more load or data.
- The user asks for a performance review/audit specifically.

## What to Analyze

1. **Database access** — N+1 query patterns, missing indexes (see [Database Architect](../database-architect/) for schema-level depth), fetching more columns/rows than needed.
2. **Algorithmic complexity** — loops over loops on data that can grow, repeated work that could be cached or computed once.

## Purpose

Review a pull request the way a senior engineer would: assess whether the change accomplishes its stated intent, is appropriately scoped, and doesn't introduce bugs, architectural drift, or maintainability regressions — then organize findings by severity like a real PR review.

## When to Use

- Reviewing a complete PR/diff (multiple files, a coherent change set) rather than a single function.
- Before approving or requesting changes on a real PR.

Differs from [Code Reviewer](../code-reviewer/): Code Reviewer is line/function-level quality; PR Reviewer additionally evaluates scope, intent-match, and whether the PR is the right size and shape as a unit of change.

## What to Analyze

1. **Intent match** — does the diff actually do what the PR title/description claims, completely?

## Purpose

Find code that is more complicated than the problem it solves, and propose a concrete simpler implementation that preserves the exact same behavior. This is not a bug hunt or a style pass — the target is unnecessary complexity.

## When to Use

- Code works correctly but is hard to read, extend, or reason about.
- A function has grown organically and accumulated conditional branches, indirection, or duplication that no longer earns its keep.
- Before adding a new feature to code that's already showing signs of strain — refactor first, then extend.

## What to Analyze

1. **Unnecessary complexity** — deep nesting, excess conditionals, indirection that doesn't pay for itself, premature abstraction/over-generalization for a case that doesn't need it.
2. **Duplication** — repeated logic that should be a shared function/module.

## Purpose

Protect applications from cascading failures when downstream dependencies (third-party APIs, microservices, databases) become slow or unresponsive, using Circuit Breakers, Bulkheads, Timeouts, and Graceful Fallbacks.

## When to Use

- Calling third-party APIs (Stripe, Twilio, OpenAI, shipment tracking) that occasionally degrade.
- Preventing thread/connection exhaustion when one downstream microservice stalls.
- Implementing graceful degradation (e.g. returning cached recommendations when AI engine is down).

## What to Analyze

1. **Circuit States**: `CLOSED` (normal), `OPEN` (failing fast without calling downstream), `HALF-OPEN` (probing recovery).
2. **Threshold Metrics**: Failure percentage threshold (e.g. >50% errors over 20 requests) and slow call duration threshold.

## Purpose

Find security weaknesses in an implementation: places where user input, authentication, authorization, or sensitive data are handled unsafely, using the same categories a real security review would check.

## When to Use

- Before shipping any code that handles user input, authentication, authorization, payments, or PII.
- Reviewing code that constructs queries, commands, or file paths from external input.
- The user asks for a "security review" or "security audit."

This skill is for defensive review of code you own or are authorized to review — not for developing exploits against systems you don't have permission to test.

## What to Analyze

## Purpose

Analyze slow or resource-intensive SQL queries, interpret EXPLAIN / ANALYZE execution plans, and rewrite queries or recommend precise indexes to eliminate sequential scans and lock contention.

## When to Use

- A query causes high CPU, memory pressure, or connection saturation on the database.
- Designing complex joins, aggregations, window functions, or subqueries.
- Diagnosing deadlocks or table lock contention under concurrent writes.

## What to Analyze

1. **Execution Plan**: Inspect cost nodes, Seq Scans, Index Scans, Bitmap Index Scans, Nested Loops vs Hash Joins.
2. **Predicate SARGability**: Identify functions on indexed columns (e.g. `WHERE DATE(created_at) = ...`) preventing index hits.

## Purpose

Model complex lifecycles (orders, payments, multi-step wizards, IoT device connections) into mathematically sound, deterministic Finite State Machines (FSMs) with explicit states, events, guards, and transition side-effects.

## When to Use

- When code is polluted with dozens of boolean flags (`isLoading`, `isSubmitted`, `hasError`, `canRetry`) creating impossible states.
- Designing distributed transaction orchestrations (Saga lifecycles).
- Modeling complex frontend forms or media player states.

## What to Analyze

1. **State Space**: Exhaustive list of discrete, mutually exclusive states.
2. **Events / Triggers**: Explicit inputs that prompt transitions.

## Purpose

Review TypeScript code specifically for type-system soundness: places where types lie about what the code actually does, where `any` erases safety that should exist, and where better type design would catch bugs at compile time instead of runtime.

## When to Use

- Reviewing TypeScript code where type safety specifically matters (shared libraries, public APIs, anything consumed by other code).
- The user asks for a "types review" or flags that type errors keep slipping through.
- Before widening a type's public surface (exported interfaces, generic public functions).

## What to Analyze

1. **`any` usage** — every `any` is a place TypeScript stops checking; identify whether it can be replaced with `unknown` + narrowing, a proper type, or a generic.
2. **Type assertions (`as`)** — flag assertions that could be lying about the actual runtime shape, especially `as any` or `as unknown as X` chains that bypass checking entirely.

## Purpose

Architect reliable, low-overhead real-time messaging protocols over WebSockets or Server-Sent Events (SSE), incorporating connection lifecycle handshakes, heartbeat ping/pong keep-alives, exponential reconnect backoff, channel multiplexing, and reconnection state recovery.

## When to Use

- Building real-time collaborative editors, live chat, trading dashboards, or notification feeds.
- Fixing zombie WebSocket connections that silently drop behind NAT firewalls.
- Implementing message ordering and missed message replay after temporary disconnection.

## What to Analyze

1. **Protocol Selection**: WebSocket (bidirectional) vs SSE (unidirectional server-to-client with native HTTP/2 multiplexing).
2. **Frame Format**: Lightweight JSON envelopes vs Binary MessagePack/Protobuf for high-frequency data.

## Purpose

Document significant architectural choices in a lightweight, immutable Architecture Decision Record (ADR) following the Michael Nygard format to maintain long-term technical context.

## When to Use

- Committing to a new framework, language, database, or major pattern.
- Changing an existing architectural standard or deprecating a system.
- Preserving the "why" behind non-obvious engineering decisions for future hires.

## What to Analyze

1. **Title & Status**: `[Number] [Title]` (e.g. `ADR-0012 Use ClickHouse for Event Analytics`) with status (`Proposed`, `Accepted`, `Superseded`, `Rejected`).
2. **Context**: What problem are we solving, and what business/technical constraints force a decision?

## Purpose

Turn a raw list of commits, PR titles, or dev notes into a clean, categorized changelog entry that a user (not just an engineer) can read and understand what changed.

## When to Use

- Preparing release notes for a new version.
- A commit history is a mix of styles/quality and needs to become one coherent changelog.
- The user pastes a list of merged PRs or commit messages and wants them turned into notes.

## What to Analyze / Do

1. **Categorize each change** — typically: Added, Changed, Fixed, Removed, Deprecated, Security (following a Keep a Changelog–style structure, or the project's existing convention if different).
2. **Rewrite for the reader, not the author** — "fix null check in auth.js" becomes "Fixed an issue where login could fail unexpectedly for some users." Focus on user-visible impact, not implementation detail, unless the audience is technical (e.g. a library's changelog for other engineers, where technical specificity is appropriate).

## Purpose

Scan a codebase and documentation to compile a structured Domain Glossary / Ubiquitous Language dictionary, resolving ambiguity around internal acronyms, overloaded terms, and domain entities.

## When to Use

- Onboarding new engineers to a domain-dense codebase (e.g. Fintech, Healthcare, Logistics, AdTech).
- Resolving naming confusion where different teams use different words for the same concept.
- Aligning engineering naming directly with product and business definitions.

## What to Analyze

1. **Domain Entities**: Key nouns used in database models and APIs (e.g. `Tenancy`, `LedgerEntry`, `Claim`).
2. **Internal Acronyms**: Decoding company or industry jargon (e.g. `MRR`, `ACH`, `KYC`, `EOD`).

## Purpose

Write a clear, well-structured commit message for a given change — one that explains *what* changed and, where non-obvious, *why*, following the project's commit convention (Conventional Commits by default unless another pattern is evident).

## When to Use

- Writing a commit message for a diff/change and want it done well.
- Reviewing an existing commit message for clarity/convention compliance.
- A project's commit history is inconsistent and needs a documented convention to follow going forward.

## What to Analyze / Do

1. **Determine the convention in use** — check recent commit history for a pattern (Conventional Commits `type(scope): subject`, or a different house style) and match it; default to Conventional Commits if none is evident.
2. **Identify the actual change type** — `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, etc. — based on what the diff actually does, not what the author might casually call it.

## Purpose

Draft comprehensive, beginner-friendly `CONTRIBUTING.md` guides, GitHub pull request templates, and issue templates to streamline open-source contributions and maintain repo code quality.

## When to Use

- Open-sourcing an internal project or launching a new public repository.
- Improving contributor onboarding when PRs consistently fail CI or lack context.
- Standardizing commit conventions and testing expectations for contributors.

## What to Analyze

1. **Prerequisites & Tooling**: Required Node/Go/Rust/Python versions, package managers, and global CLI tools.
2. **Local Setup Steps**: Exact shell commands from `git clone` to running tests locally.

## Purpose

Produce clear, structured technical documentation from a given source — source code, requirements, meeting notes, or a mix — that explains what something is, how it works, and how to use it, for the audience it's meant for.

## When to Use

- A feature, module, API, or system has no documentation, or what exists is stale.
- Turning requirements or design notes into a reference doc.
- The user has working code but needs it explained for other engineers, or non-engineers.

## What to Analyze / Do

1. **Identify the audience** — engineers integrating with this, engineers maintaining it, or non-technical stakeholders — and match depth/jargon accordingly. Ask if unclear and it meaningfully changes the doc.
2. **Establish structure before writing prose** — overview, how it works, usage/examples, configuration, edge cases/limitations, is a reasonable default shape; adapt to what the source material actually supports.

## Purpose

Translate complex, jargon-heavy technical documents (incident postmortems, multi-quarter migration plans, architecture RFCs) into concise, high-impact executive summaries for CTOs, VPs, and non-technical stakeholders.

## When to Use

- Communicating major production outage postmortems to company leadership.
- Pitching large infrastructure investments requiring budget sign-off.
- Preparing quarterly engineering board updates and business impact reviews.

## What to Analyze

1. **Bottom Line Up Front (BLUF)**: What happened, what does it cost, and what is required in 2 sentences.
2. **Business Impact**: Quantify downtime, lost revenue, customer trust impact, and SLA penalty risks.

## Purpose

Produce a professional, complete README for a GitHub project that lets a newcomer understand what the project is, install it, and start using it — without needing to read the source first.

## When to Use

- A repository has no README, or one that's thin/outdated.
- Preparing a project for public release or wider internal sharing.
- The user asks for "a README" for a project.

## What to Analyze / Do

1. **Determine what the project actually is** — from the codebase, package manifest, or the user's description: language/framework, what it does, its entry points.
2. **Cover the standard sections**, adapted to project type:

## Purpose

Transform raw developer commit logs and PR titles into compelling, customer-centric release notes that highlight user value, new features, bug fixes, and breaking changes.

## When to Use

- Publishing weekly, monthly, or major version product releases.
- Writing app store update descriptions and developer changelog entries.
- Creating internal stakeholder release announcements.

## What to Analyze

1. **Audience**: End-users vs API developers vs Enterprise admins.
2. **Feature Highlights**: Group related changes by customer impact rather than PR order.

## Purpose

Author comprehensive, highly structured Request for Comments (RFC) engineering proposals that clearly articulate the motivation, technical design, alternatives considered, security implications, and rollout phases for major technical initiatives.

## When to Use

- Proposing large architectural refactors, new microservices, or shared libraries.
- Introducing major third-party vendors or new programming languages to the stack.
- Building consensus across distributed engineering teams before writing code.

## What to Analyze

1. **Problem Statement & Motivation**: What business or engineering pain point requires solving now?
2. **Proposed Solution & Architecture**: System diagrams, API payloads, schema migrations, and sequence flows.

## Purpose

Produce clear, foolproof, executable operational runbooks for on-call engineers to diagnose, mitigate, and resolve production alerts under pressure.

## When to Use

- Creating runbooks for new microservices, alerts, or cron jobs.
- Standardizing incident response procedures across engineering teams.
- Documenting disaster recovery failovers, certificate renewals, and manual database rollbacks.

## What to Analyze

1. **Alert Definition**: Alert name, firing trigger threshold, severity, and impacted customer services.
2. **Triage & Diagnosis**: Step-by-step commands and dashboard links to verify if it is a real issue or false positive.

## Purpose

Write developer-first "Getting Started" guides, SDK quickstarts, and interactive code snippets that enable engineers to make their first successful API call in under 3 minutes.

## When to Use

- Launching a public API, developer SDK, or open-source library.
- High developer drop-off between creating an API key and making their first request.
- Writing documentation for multi-language client libraries (Node, Python, Go, cURL).

## What to Analyze

1. **Time-to-First-Hello-World**: Minimize steps between package install and first successful response.
[Credential-related source omitted]

## Purpose

Turn raw, informal development notes (a scratch list of what got done, blockers, half-finished thoughts) into a clear, professional status update suitable for sharing with a team or stakeholder.

## When to Use

- Writing a daily/weekly status update from rough notes.
- Converting a stream-of-consciousness list of "did X, working on Y, blocked on Z" into something shareable.
- Standardizing status update format across a team.

## What to Analyze / Do

1. **Separate signal from noise** — not every micro-task belongs in a status update; group related work into meaningful lines (5 small bug fixes on the same feature become one line, not five).
2. **Organize into clear sections** — typically: Done (this period) / In Progress / Blocked / Next. Adapt if the team has an existing format.

## Purpose

Analyze and optimize continuous integration and deployment pipelines (GitHub Actions, GitLab CI, CircleCI) to dramatically cut build minutes, reduce compute costs, eliminate redundant jobs, and speed up developer feedback loops.

## When to Use

- CI pipelines take >15 minutes, slowing down pull request velocity.
- GitHub Actions monthly billing bills are spiking.
- Investigating non-deterministic flaky steps or cache-miss penalties.

## What to Analyze

1. **Dependency & Build Caching**: Caching `node_modules`, `~/.cargo`, `~/.m2`, Go build cache, Docker build layers (Buildx / GitHub Actions Cache backend).
2. **Job Parallelization & Matrix Builds**: Running lint, typecheck, unit tests, and E2E suites concurrently instead of sequentially.

## Purpose

Compress, filter, and structure codebase context and instructions provided to AI coding agents and LLMs, maximizing token efficiency, eliminating noise, and preventing context window dilution.

## When to Use

- Feeding large codebases, trace logs, or documentation into AI assistants.
- Hitting token context limits in AI agent sessions.
- Improving LLM reasoning accuracy by stripping unneeded boilerplate and node_modules cruft.

## What to Analyze

1. **Signal-to-Noise Ratio**: Strip minified bundles, lockfiles, compiled artifacts, and repetitive mock fixtures.
2. **Skeleton & Interface Extraction**: Extract TypeScript interfaces, class signatures, and exported function headers rather than full 1,000-line function bodies.

## Purpose

Resolve difficult, tangled Git merge and rebase conflicts by analyzing both branches' underlying intent, syntax AST changes, import reorganizations, and semantic context rather than blindly picking incoming vs current changes.

## When to Use

- Resolving massive merge conflicts after rebasing a long-lived feature branch onto main.
- Reconciling concurrent refactorings (e.g. one branch renamed a function, another branch added new calls to it).
- Fixing lockfile conflicts (`pnpm-lock.yaml`, `package-lock.json`, `Cargo.lock`).

## What to Analyze

1. **Branch Intent Analysis**: What did Branch A (Incoming) change and why? What did Branch B (Current) change and why?
2. **Syntactic Merging**: Harmonizing import statements, exports, and interface definitions from both branches.

## Purpose

Generate a set of technical interview questions for a given role/skill area, paired with a concrete evaluation rubric — so interviews are structured and comparable across candidates, not improvised each time.

## When to Use

- Preparing to interview a candidate for a specific role or skill area.
- An interview loop needs consistent questions across interviewers.
- Existing interview questions feel stale, too generic, or don't actually test what the role needs.

## What to Analyze / Do

1. **Clarify what's actually being assessed** — a specific skill area (e.g. "React component design," "SQL query writing," "system design for a backend role"), seniority level, and time budget.
2. **Generate questions that discriminate** — questions where a strong candidate's answer clearly differs from a weak one, not questions with a single memorizable correct answer that only tests recall.

## Purpose

Convert raw, unstructured meeting notes or a transcript into a clean summary of what was decided and what needs to happen next — the artifact people actually reread, instead of scrolling back through a wall of raw notes.

## When to Use

- A meeting just happened and raw notes/transcript exist that need to become a shareable summary.
- Someone missed a meeting and needs to catch up without reading the full transcript.
- A recurring meeting needs a consistent summary format over time.

## What to Analyze / Do

1. **Separate discussion from decisions** — most of a meeting is discussion; only some of it results in an actual decision. Distinguish clearly between "this was debated" and "this was decided."
2. **Extract action items** — each with an owner if stated or clearly implied, and a deadline if one was mentioned; mark "owner unclear" rather than guessing.

## Purpose

Architect scalable monorepo structures (Turborepo, Nx, pnpm workspaces) with strict package boundary isolation, shared internal UI/config/type packages, deterministic dependency graphs, and remote build caching.

## When to Use

- Consolidating multiple standalone repositories into a single unified monorepo.
- Setting up shared UI component libraries, TypeScript configs, or ESLint rules across apps.
- Fixing slow monorepo build times using incremental build pipelines and computation caching.

## What to Analyze

1. **Workspace Topography**: `apps/*` (deployable targets) vs `packages/*` (internal shared libraries).
2. **Dependency Graph Directionality**: Ensuring apps depend on packages, and leaf packages never depend upward.

## Purpose

Generate concise, comprehensive, and actionable on-call shift handover reports to transfer operational context smoothly to the incoming engineer without lost details.

## When to Use

- Weekly or daily on-call shift transitions.
- Handing over active or mitigated incidents across time zones (Follow-the-Sun).
- Summarizing alert volume and noise for engineering managers.

## What to Analyze

1. **Active / Ongoing Incidents**: Any un-resolved or partially mitigated P1/P2 issues.
2. **Recent Deployments & Feature Flags**: High-risk changes toggled during the shift.

## Purpose

Generate an onboarding guide for a new engineer joining a project — grounded in the codebase's actual structure and setup, not a generic checklist — so a newcomer can get from "cloned the repo" to "made a first meaningful change" with less hand-holding.

## When to Use

- A project has no onboarding doc, or an outdated one that no longer matches the codebase.
- Preparing for a new hire or new contributor joining.
- The user asks for "onboarding docs" or "getting started" documentation for a codebase.

## What to Analyze / Do

1. **Determine real setup steps** — from the actual package manifest/README/scripts, not assumed commands. Don't invent steps that aren't verifiable from the source.
2. **Summarize the architecture** — the major components/services and how they relate, at a level a newcomer needs before diving into any one file.

## Purpose

Transform loose, ambiguous, or incomplete user requests into high-precision, constraint-driven prompts with explicit roles, context requirements, step-by-step reasoning directives, output schemas, and boundary rules.

## When to Use

- When an initial prompt produces hallucinated, generic, or off-target AI responses.
- Writing reusable prompt templates or system instructions for AI agent workflows.
- Refining complex coding or architectural prompts before executing them.

## What to Analyze

1. **Role & Persona**: Establish precise expertise level (e.g. "Senior Rust Systems Engineer").
2. **Context & Inputs**: Identify missing variables, code snippets, or environment specs.

## Purpose

Turn raw retro input (a scattered list of what went well, what didn't, and ideas to try) into a structured summary with clustered themes and concrete, ownable action items — so retros produce follow-through instead of just catharsis.

## When to Use

- After a sprint/iteration retro, with raw notes (sticky notes, a shared doc, verbal notes) that need structuring.
- A team's retros tend to surface the same complaints repeatedly with no visible action — worth using this to force clustering and concrete actions.

## What to Analyze / Do

1. **Cluster related raw items into themes** — several individually-worded complaints about "too many meetings," "context switching," "no focus time" likely cluster into one theme (interruption/focus-time issues), not three separate items.
2. **Separate went-well from went-poorly from ideas-to-try** clearly.
3. **Convert the most significant themes into concrete action items** — not every theme needs an action (some are just useful signal), but recurring or high-impact ones should get one.

## Purpose

Break one task/ticket down into concrete, sequenced subtasks small enough to just start on. Deliberately atomic and single-task scoped — for whole-project phasing and cross-team dependencies, see [Project Planner](../../architecture/project-planner/) instead.

## When to Use

- A single ticket/task feels too large or vague to start on directly.
- Estimating a task requires understanding its real sub-steps first.
- Handing a task to someone else and want to leave them a concrete starting checklist.

Differs from [Project Planner](../../architecture/project-planner/): that skill produces phases/milestones for a multi-task project; this skill produces the subtask checklist for one task within that project.

## What to Analyze / Do

## Purpose

Audit and convert sprawling, informal technical debt complaints into a rigorously prioritized, ROI-driven engineering burndown backlog ranked by Risk, Developer Drag, and Remediation Effort.

## When to Use

- Planning engineering allocation for technical debt sprints or quarterly OKRs.
- Convincing product managers to prioritize refactoring by translating tech debt into developer velocity and reliability metrics.
- Establishing an ongoing, sustainable 20% technical debt paydown workflow.

## What to Analyze

1. **Debt Categorization**: Architecture Debt (monolith coupling), Test Debt (flaky E2E tests), Tooling Debt (slow CI builds), Dependency Debt (EOL libraries).
2. **Developer Drag Factor (1-5)**: How many hours per engineer does this issue waste weekly?

## Purpose

Detect and correct human cognitive distortions in engineering planning, architectural choices, and project roadmaps to avoid predictable traps.

## When to Use

- Reviewing sprint estimates or project milestone plans.
- When a team insists on maintaining an obsolete custom system (sunk cost).
- When a design heavily mirrors the author's previous company stack (availability bias / law of the instrument).

## What to Analyze

1. **Sunk Cost Fallacy**: Continuing an unviable strategy because of prior invested hours.
2. **Planning Fallacy & Optimism Bias**: Assuming perfect zero-defect execution with no buffer.

## Purpose

Given two or more candidate solutions to the same problem, evaluate them against explicit criteria and trade-offs, and produce one clear, defensible recommendation — not a noncommittal summary of pros and cons.

## When to Use

- The user has already narrowed a decision down to a shortlist of real options.
- A choice has real trade-offs and no option is a strict superset of the others.
- The user needs a documented rationale they can share with others (a design doc, an ADR).

## What to Analyze

1. **Confirm the options** being compared and the actual decision being made.
2. **Establish criteria** — ask for or infer the dimensions that matter (cost, latency, team familiarity, time to ship, long-term maintainability, reversibility). State them explicitly before scoring.

## Purpose

Slow down on a hard problem: decompose it into its component sub-problems, generate more than one candidate approach, reason through each honestly, and only then converge on a recommendation. This exists to counteract jumping to the first plausible-sounding solution on problems that deserve better.

## When to Use

- The problem has multiple interacting constraints (technical, product, resourcing) and the right approach isn't obvious.
- A first-instinct answer feels too easy for how hard the problem sounded.
- The user explicitly asks to "think deeply," "reason through," or "really think this through" on something.

Do not use for simple, well-understood tasks — decomposing a one-step problem into stages wastes the user's time.

## What to Analyze / Do

## Purpose

Given a stated position, decision, or idea, construct the strongest good-faith argument *against* it — even if that argument is ultimately weaker than the case for it. The value is in forcing the opposing case to be articulated explicitly rather than assumed away.

## When to Use

- The user has already decided on something and wants to know what a smart opponent would say against it.
- A group or team seems to be converging on consensus too quickly.
- Before finalizing a decision that's hard to reverse.

This differs from [GrillMe](../grill-me/): GrillMe attacks weaknesses broadly across many angles; Devil's Advocate builds one coherent, sustained counter-position, as if arguing the other side in a debate.

## What to Analyze

## Purpose

Strip away industry cargo-culting, legacy conventions, and reasoning-by-analogy to rebuild solutions strictly from fundamental constraints (physics, math, raw computing limits, core business rules).

## When to Use

- When existing solutions are bloated, expensive, or overly complex because "that is how everyone does it."
- When rethinking an architectural component or feature from the ground up.
- When evaluating whether an established best practice actually applies to your specific constraints.

## What to Analyze

1. **Identify the Core Objective**: What is the non-negotiable end goal in one sentence?
2. **Catalog Received Assumptions**: List every assumption inherited from typical stacks, standard patterns, or prior systems.

## Purpose

Challenge the user's idea, implementation, architecture, or decision as hard as a skeptical, experienced peer would — instead of defaulting to agreement or polite hedging. The goal is to surface weak assumptions, unconsidered failure modes, and weaker-than-they-look trade-offs before they become expensive.

## When to Use

- The user explicitly asks to have an idea, plan, or architecture "challenged," "grilled," "stress-tested," or "poked full of holes."
- Before committing to a significant technical or product decision.
- When a plan sounds too clean and hasn't been argued against yet.

Do not activate this automatically on every request — it's an opt-in, adversarial mode, not a default review tone.

## What to Analyze

## Purpose

Uncover hidden risks before launch by assuming the project has completely failed 6 months in the future, then working backward to diagnose why.

## When to Use

- Prior to kicking off a major migration, rewrite, or product launch.
- When a plan feels "too smooth" and team members are hesitant to voice doubts.
- Before committing to a major third-party dependency or cloud vendor.

## What to Analyze

1. **The Disaster Scenario**: Assume it is 6 months post-launch and the project was rolled back or caused massive downtime.
2. **Failure Vectors**:

## Purpose

Turn a vague request ("make it faster," "add user profiles," "it should feel more modern") into explicit, checkable functional and technical requirements, and surface the ambiguities that need an answer before implementation can start.

## When to Use

- A feature request, ticket, or user message is underspecified for direct implementation.
- Before starting implementation on anything nontrivial, to confirm scope with the requester.
- When a team keeps re-litigating "wait, was that supposed to include X?" mid-build.

## What to Analyze / Do

1. **Restate the request** in plain language to confirm the core intent.
2. **Extract functional requirements** — what the system must do, from a user's perspective, as discrete checkable statements ("User can reset their password via email").

## Purpose

Drill past surface-level symptoms and immediate triggers to uncover the systemic, architectural, and organizational root causes of engineering failures.

## When to Use

- Post-incident reviews and postmortems.
- Recurring bugs that keep resurfacing after quick patches.
- Flaky systems where the immediate fix failed to prevent secondary fallout.

## What to Analyze

1. **Immediate Trigger**: What directly caused the error?
2. **Propagation Chain**: How did the failure cascade through the system?

## Purpose

Anticipate the multi-order ripple effects ("and then what?") of architectural changes, API deprecations, schema updates, or rate limit adjustments across interrelated systems, teams, and user habits.

## When to Use

- Proposing a breaking change or deprecation.
- Adding strict rate limits, database indexes, or caching layers.
- Changing pricing tiers, billing models, or developer API quotas.

## What to Analyze

1. **First-Order Effect (Immediate Intent)**: What does this change directly accomplish?
2. **Second-Order Effects (Downstream Systems)**: How do upstream callers, batch jobs, and databases react?

## Purpose

Unpack vague, incomplete, or underspecified requirements by asking disciplined, structured Socratic questions that force clarity on edge cases, user intent, and non-functional requirements before writing code.

## When to Use

- When handed a one-line ticket or vague feature request ("Make search better", "Add export").
- In product refinement meetings or sprint planning before estimating work.
- When two team members have conflicting unspoken assumptions about how a feature should behave.

## What to Analyze

1. **Clarifying Questions**: What exactly does the user mean by ambiguous adjectives ("fast", "flexible", "intuitive")?
2. **Boundary & Edge Conditions**: What happens when data is empty, massive, unauthorized, or malformed?

## Purpose

Quantify and structure complex technical evaluations by comparing alternatives against explicit, weighted decision criteria with rationale.

## When to Use

- Choosing between frameworks, databases, libraries, or architectural patterns.
- Resolving engineering stalemates on technology selection.
- Providing objective justification for RFCs and executive presentations.

## What to Analyze

1. **Candidate Options**: 2 to 4 viable technical contenders.
2. **Evaluation Dimensions**: Performance, developer experience, maintenance cost, ecosystem maturity, learning curve, vendor lock-in.

## Purpose

Review authentication and authorization flows in depth — login, session management, token lifecycle, logout, and SSO/OAuth integrations — going deeper into this one area than [Security Auditor](../../development/security-auditor/)'s general pass covers.

## When to Use

- Reviewing or designing login, session, or logout code.
- Integrating an SSO/OAuth provider.
- Debugging auth-related bugs (unexpected logouts, session persistence issues, "why is this user still logged in").

## What to Analyze

1. **Session lifecycle** — session creation on login, expiry (both idle timeout and absolute max lifetime), and invalidation on logout — confirm logout actually invalidates server-side state, not just clears a client-side cookie.
2. **Session fixation** — is a new session ID issued on login (not reusing a pre-login session ID), preventing an attacker from fixing a victim's session ID before authentication?

## Purpose

Review how a feature collects, stores, processes, and retains personal data against common privacy-framework principles — data minimization, purpose limitation, consent, retention limits, and user rights (access/deletion/export) — flagging gaps before they become compliance problems.

## When to Use

- A feature collects, stores, or processes personal data (PII) — user profiles, tracking/analytics, location data, health/financial data, anything third-party-shareable.
- Reviewing a data flow or new integration for privacy implications.
- Before shipping something that touches user data in a new way.

**This is not legal advice.** Real compliance sign-off (GDPR, CCPA, HIPAA, etc.) requires qualified legal review — this skill flags likely gaps for a human/legal team to evaluate, not a compliance certification.

## What to Analyze

## Purpose

Audit web application endpoints for cross-origin vulnerabilities, overly permissive CORS headers (`Access-Control-Allow-Origin: *` with credentials), missing Anti-CSRF tokens on cookie-based state-changing endpoints, and weak SameSite cookie attributes.

## When to Use

- Exposing new public or authenticated API endpoints.
- Setting up single sign-on (SSO) or cross-subdomain API sharing.
- Reviewing cookie security configurations and pre-flight HTTP headers.

## What to Analyze

1. **CORS Headers**:
   - Inspect `Access-Control-Allow-Origin`, `Access-Control-Allow-Credentials`, and wildcard reflection of `Origin` header.

## Purpose

Audit source code and infrastructure configurations for cryptographic weaknesses: obsolete ciphers (MD5, SHA1, DES, RC4), hardcoded encryption keys, weak key derivation functions (KDFs), insecure random number generators, and flawed token signing.

## When to Use

- Reviewing password hashing, encryption at rest, and secret token generation.
- Implementing asymmetric JWT signing (RS256 / EdDSA) or HMAC validation.
- Validating TLS cipher suite configurations and webhook signature verification.

## What to Analyze

1. **Password Hashing**: Use of Argon2id or bcrypt (cost factor >= 12) vs obsolete plain SHA256/MD5.
2. **Symmetric Encryption**: AES-256-GCM / ChaCha20-Poly1305 (authenticated encryption) vs insecure AES-ECB / AES-CBC without HMAC.

## Purpose

Define automated data anonymization, pseudonymization, and redaction rules to prevent Personally Identifiable Information (PII), credit card numbers, passwords, and API keys from leaking into application logs, error monitoring tools, and staging databases.

## When to Use

- Sanitizing production database snapshots for local development or QA environments.
- Configuring log scrubber rules (Datadog, Pino, Winston, Logstash).
- Complying with GDPR, HIPAA, or PCI-DSS redaction mandates.

## What to Analyze

1. **PII Cataloging**: Email addresses, phone numbers, SSNs, IP addresses, full names, physical addresses.
2. **Secret Identification**: Passwords, bearer tokens, JWTs, API keys, credit card PANs / CVVs.

## Purpose

Triage and evaluate automated security alerts (Dependabot, Snyk, GitHub Advisory, Trivy) to determine true exploitability in your specific application context, distinguishing genuine high-risk threats from harmless dev-dependency false positives.

## When to Use

- Reviewing a barrage of automated Dependabot or Snyk PRs.
- Preparing for security compliance reviews where open CVEs must be justified or remediated.
- Deciding whether a vulnerability requires an emergency out-of-band deployment.

## What to Analyze

1. **Vulnerability Mechanics**: What exact function or API triggers the vulnerability (e.g. Prototype Pollution in `lodash.merge`, ReDoS in regex parser)?
2. **Reachable Attack Surface**: Does your application actually import and call the vulnerable function with untrusted user input?

## Purpose

Turn raw, informal incident notes (timestamps, Slack messages, half-remembered sequence of events) into a structured, blameless postmortem document that captures what happened, why, and what changes as a result.

## When to Use

- After an incident/outage, once it's resolved and needs to be documented.
- Raw notes/timeline exist (from an incident channel, monitoring alerts, or people's recollections) and need to become a coherent document.
- A team wants to standardize postmortem format.

## What to Analyze / Do

1. **Build a clear timeline** — order events chronologically with timestamps where available; note where the timeline has gaps or uncertainty rather than inventing precision that isn't there.
2. **Separate root cause from contributing factors** — the root cause is what actually triggered the incident; contributing factors are things that made it worse or harder to detect/resolve (e.g. "alerting was misconfigured" is a contributing factor to detection delay, not necessarily the root cause of the outage itself).

## Purpose

Audit and harden JSON Web Token (JWT) authentication, signing, and verification pipelines to eliminate critical vulnerabilities: algorithm confusion (`alg: none`, HMAC vs RSA/ECDSA confusion), weak signing secrets, missing claim validations, and lack of revocation mechanisms.

## When to Use

- Implementing or reviewing JWT authentication for APIs, single sign-on, or microservices.
- Passing security audits and penetration tests on token validation logic.
- Setting up token rotation, refresh token revocation, and asymmetric key pairs (JWKS).

## What to Analyze

1. **Algorithm Whitelisting**: Explicitly enforcing expected algorithms (e.g. `algorithms: ['RS256']`) preventing `none` or public-key-as-HMAC attacks.
2. **Mandatory Standard Claims**: Enforcing `exp` (short expiration, max 15m), `iat`, `nbf`, `iss` (issuer validation), and `aud` (audience validation).

## Purpose

Architect scalable, secure authorization frameworks supporting Role-Based Access Control (RBAC), Attribute-Based Access Control (ABAC), fine-grained permissions, and strict multi-tenant data isolation.

## When to Use

- Implementing workspace roles (Owner, Admin, Editor, Viewer) in a B2B SaaS application.
- Designing resource-level permissions (e.g. "Can edit document only if document belongs to user's team AND status is draft").
- Preventing Insecure Direct Object References (IDOR) and cross-tenant data leakage.

## What to Analyze

1. **Authorization Paradigm**: RBAC (role assigned to user) vs ABAC (policy based on user attributes + resource attributes + environment).
2. **Permission Granularity**: Action-resource strings (e.g. `documents:write`, `billing:manage`) or numeric bitmasks.

## Purpose

Find hardcoded secrets — API keys, passwords, tokens, private keys, connection strings with embedded credentials — sitting in code or config where they shouldn't be. Narrow and mechanical by design, unlike [Security Auditor](../../development/security-auditor/)'s broader vulnerability sweep.

## When to Use

- Before committing/opening a PR, especially after copy-pasting example code or config from elsewhere.
- Auditing an existing codebase for accidentally-committed secrets, e.g. before making a private repo public.
- The user specifically asks to check for "hardcoded secrets," "leaked credentials," or similar.

## What to Analyze

[Credential-related source omitted]
[Credential-related source omitted]

## Purpose

Automate and structure evidence collection for SOC 2 Type II compliance audits across the Trust Services Criteria (Security, Availability, Confidentiality), organizing access reviews, change control pull requests, encryption proof, and disaster recovery drill logs.

## When to Use

- Preparing for annual SOC 2 Type I or Type II compliance audits.
- Configuring automated compliance platforms (Vanta, Drata, Secureframe).
- Creating tamper-proof audit trails for change management and production database access.

## What to Analyze

1. **Change Management (CC8.1)**: Proof that all production deployments link to approved PRs with 2+ code reviews and passing CI checks.
2. **Access Control & Least Privilege (CC6.1 - CC6.3)**: Quarterly user access review logs, SSO MFA enforcement, and zero static root keys.

## Purpose

Identify likely threats and attack surfaces for a feature or system *before* it's built, so mitigations are designed in from the start rather than patched on after a [Security Auditor](../../development/security-auditor/) review finds them in finished code.

## When to Use

- Designing a new feature that touches user data, authentication, payments, or external/untrusted input.
- Before finalizing an architecture that introduces a new trust boundary (a new service, a new external integration, a new user-facing input).
- The user asks for a "threat model" or "what could go wrong from a security angle" on something not yet built.

Differs from [Security Auditor](../../development/security-auditor/): that skill reviews *existing* code for concrete vulnerabilities; this skill reasons about a *design* before code exists, to catch classes of risk while they're still cheap to address.

## What to Analyze / Do

## Purpose

Formulate structured chaos engineering experiments to empirically test system resilience against infrastructure disruptions (network latency, pod crashes, database failovers, DNS outages).

## When to Use

- Validating high-availability claims prior to peak shopping events (Black Friday) or major launches.
- Verifying circuit breakers, retries, and fallback caches actually work under real network turbulence.
- Testing alerting thresholds and on-call paging during automated failure simulations.

## What to Analyze

1. **Steady State Hypothesis**: Measurable baseline metric representing normal operation (e.g., 99.9% 2xx responses, latency p95 < 250ms).
2. **Turbulence Variable**: Specific failure injected (e.g., 500ms latency to payment gateway, killing random Redis replicas).

## Purpose

Design consumer-driven contract testing suites (Pact, OpenAPI contract validators) to ensure microservices and frontend/backend interfaces stay compatible without requiring expensive, brittle end-to-end test environments.

## When to Use

- Microservices that communicate over HTTP REST, gRPC, or message queues.
- Preventing frontend outages caused by uncoordinated backend API payload changes.
- Replacing flaky end-to-end staging environments with fast, isolated CI contract verification.

## What to Analyze

1. **Consumer Expectations**: What fields does the client actually read and rely on?
2. **Provider State Definitions**: Setting up backend database fixtures to satisfy contract scenarios.

## Purpose

Architect a resilient, non-flaky End-to-End (E2E) test suite using Playwright or Cypress focused on core business user journeys (authentication, checkout, workspace invitation, data export) while keeping test run times fast.

## When to Use

- Establishing an automated E2E smoke and regression suite.
- Refactoring brittle E2E tests filled with arbitrary `sleep()` calls and unstable CSS selectors.
- Prioritizing which test scenarios must run on pull requests vs nightly builds.

## What to Analyze

1. **Critical User Journeys (CUJs)**: Identify flows where a failure stops users from converting or using core features.
2. **Stable Locators**: Prioritize user-facing accessibility locators (`getByRole`, `getByLabel`, `getByText`) over brittle CSS hierarchy selectors.

## Purpose

Enumerate the edge cases a given piece of functionality is likely to mishandle — unusual input, boundary values, empty/missing states, and unexpected user behavior — the class of case that a "does it work for the normal case" pass typically skips.

## When to Use

- Before shipping something that handles user input or external data.
- After writing normal-case tests, to find what's still missing.
- Specifically want edge cases enumerated, separate from a general bug hunt (see [Bug Hunter](../../development/bug-hunter/) for defects in existing code; this skill is about enumerating cases to consider, whether or not code exists yet).

## What to Analyze

1. **Boundary values** — zero, negative, empty string/array/object, exactly at a limit (min/max), one below/above a limit.
2. **Empty & missing states** — no data yet (first-time user), data deleted mid-session, a required relationship missing (e.g. a comment whose author was deleted).

## Purpose

Find the actual cause of an intermittently-failing test and fix it properly, rather than reaching for a retry wrapper that hides the flake while leaving the underlying nondeterminism in place.

## When to Use

- A test passes locally but fails in CI, or fails maybe one run in ten.
- Tests fail when run in a different order, in parallel, or on a slower machine.
- A team has started ignoring or auto-retrying certain tests.

## What to Analyze

1. **Timing and async assumptions** — fixed `sleep`/timeout waits instead of waiting for the actual condition; assertions that race an unawaited promise; anything that passes on a fast machine and fails on a loaded CI runner.
2. **Shared mutable state** — module-level variables, singletons, or a database not reset between tests, so a test's outcome depends on what ran before it.

## Purpose

Design coverage-guided fuzz testing harnesses and property-based tests (AFL, libFuzzer, Atheris, Go native `testing.F`, fast-check) that generate millions of pseudo-random, adversarial inputs to discover buffer overflows, unhandled panics, assertion failures, and infinite loops.

## When to Use

- Testing data parsers (JSON, XML, YAML, binary protocols, image decoders).
- Validating cryptographic algorithms, compilers, and serialization engines.
- Securing untrusted user input handlers against malicious exploit payloads.

## What to Analyze

1. **Fuzz Target Entry Point**: Minimal, deterministic function signature accepting byte slices or structured objects.
2. **Seed Corpus**: High-quality initial valid samples to guide mutation algorithms toward deeper code paths.

## Purpose

Create realistic, multi-phase performance and stress testing scripts modeling authentic user traffic patterns (browsing, authentication, cart checkout, search) with proper ramp-up and threshold gates.

## When to Use

- Benchmarking system throughput and maximum capacity limits.
- Validating autoscaling triggers and database connection limits under load.
- Setting up CI performance regression testing gates.

## What to Analyze

1. **Traffic Profile**: Ramp-up, sustained peak load, stress spikes, and ramp-down phases.
2. **User Journey Distribution**: Weighted action ratios (e.g., 70% browse/search, 20% add to cart, 10% checkout).

## Purpose

Synthesize privacy-safe, edge-case-heavy test fixtures, mock API responses, and database seed data covering diverse data shapes, boundary values, and unicode variations.

## When to Use

- Seeding unit and end-to-end test suites with realistic mock records.
- Creating local mock APIs for frontend development before the backend is built.
- Replacing dangerous production database dumps with anonymized synthetic datasets.

## What to Analyze

1. **Data Model & Relationships**: Foreign key links, nested arrays, and enum constraints.
2. **Realistic Variety**: Realistic realistic names, addresses, emails, timestamps, and currency amounts.

## Purpose

Evaluate the true fault-detection capability of a test suite by simulating code mutations (inverting conditionals, altering arithmetic, removing function calls) and highlighting tests that pass despite broken logic.

## When to Use

- A codebase has 90%+ line coverage but bugs still regularly slip into production.
- Reviewing unit tests that assert on execution without verifying state changes.
- Setting up Stryker or Mutmut mutation testing in critical packages.

## What to Analyze

1. **Mutant Categories**:
   - Conditional Boundary Mutations (`>` swapped for `>=`).

## Purpose

Audit test suites for brittle, oversized snapshot tests (Jest/Vitest `toMatchSnapshot()`) that create false alarms during trivial styling updates, blind `-u` approval habits, and slow CI runs, replacing them with precise semantic assertions.

## When to Use

- Developers routinely run `jest -u` without reading git diffs because snapshots break on every commit.
- Huge 500-line JSON/HTML snapshots stored in repository bloating git history.
- Distinguishing when inline snapshot testing is valuable vs when it provides illusory test coverage.

## What to Analyze

1. **Snapshot Granularity**: Giant DOM tree snapshots vs targeted component state / schema snapshots.
2. **Volatile Data**: Dynamic dates, random UUIDs, or counter variables causing non-deterministic snapshot diffs.

## Purpose

Convert a set of requirements (functional spec, user story, acceptance criteria) into structured test cases — the kind used for manual QA or as a blueprint for automated test scripts — each with clear preconditions, steps, and expected results.

## When to Use

- Requirements exist (or were just extracted, e.g. via [Requirements Extractor](../../reasoning/requirements-extractor/)) and need a test plan before or during implementation.
- QA needs a structured document to execute manually.
- Preparing acceptance criteria for a feature sign-off.

Differs from [Test Generator](../test-generator/): this produces human-readable test *cases* (steps + expected results, framework-agnostic), not executable code.

## What to Analyze / Do

## Purpose

Find the testing gaps that actually matter — untested *behaviors* weighted by risk — instead of chasing a line-coverage percentage that can be high while the important paths remain unverified.

## When to Use

- Deciding where to invest limited testing effort next.
- Coverage numbers look acceptable but bugs keep escaping to production.
- Before modifying risky code, to find out what's currently protecting it (and what isn't).

Differs from [Test Generator](../test-generator/): that writes tests; this decides *which* tests are worth writing first.

## What to Analyze

## Purpose

Generate tests that actually verify behavior — correctness under normal input, boundary conditions, and failure modes — rather than tests that exist only to move a coverage percentage.

## When to Use

- Code has no tests, or existing tests don't cover the behavior that matters.
- Before refactoring, to lock in current behavior first.
- The user asks for tests for a specific function/module/component.

## What to Analyze / Do

1. **Understand actual behavior** — read the implementation (not just the function name/docstring) to know what it really does, including edge cases it may or may not handle.
2. **Cover the happy path** — normal, expected input produces the expected output.

## Purpose

Audit a UI implementation against core accessibility principles so it's usable by people relying on keyboard navigation, screen readers, or other assistive technology — not just usable with a mouse and full vision.

## When to Use

- Before shipping any user-facing UI, especially public-facing products.
- Reviewing a form, modal, or interactive component specifically.
- The user asks for an accessibility review/audit, or mentions WCAG/a11y compliance requirements.

## What to Analyze

1. **Semantic HTML** — using actual `<button>`, `<a>`, `<nav>`, `<form>`, heading levels (`<h1>`–`<h6>`) instead of generic `<div>`/`<span>` with click handlers or visual-only styling standing in for structure.
2. **Keyboard navigation** — every interactive element reachable and operable via keyboard alone (Tab, Enter/Space, Escape for dismissible elements), with a visible focus indicator.

## Purpose

Generate cohesive, accessible, and theme-ready color palettes mapped into semantic design tokens (background, surface, text, border, primary, destructive, warning, success) for light and dark modes with guaranteed WCAG contrast ratios.

## When to Use

- Bootstrapping a new brand design system or UI component library.
- Implementing dark mode on an existing light-only website.
- Fixing accessibility color contrast failures across text and interactive elements.

## What to Analyze

1. **Brand Primaries**: Core brand identity hue and saturation.
2. **Perceptual Uniformity**: Using OKLCH or HSL for balanced lightness steps (50 to 950).

## Purpose

Design clean, scannable, and actionable analytics dashboard components (KPI summary cards, trend comparison badges, inline sparklines, progress gauges) adhering to Edward Tufte's data-ink ratio and accessibility principles.

## When to Use

- Building executive analytics overviews, SaaS metrics dashboards, or billing usage widgets.
- Fixing cluttered dashboards that display overwhelming numbers with no context or trend indications.
- Designing responsive grid layouts for dashboard tiles across desktop and mobile screens.

## What to Analyze

1. **Core Metric Hierarchy**: Primary value (large typography) vs Secondary context (timeframe, vs last month).
2. **Trend Indicators**: Percentage delta (`+14.2%`), semantic color (green/red with accessible icons), and reference baseline.

## Purpose

Design accessible, high-performance data tables and grids that support massive datasets, dense information architecture, multi-column sorting, column reordering, inline editing, and virtualization.

## When to Use

- Building enterprise dashboards, CRM lists, log viewers, or financial data grids.
- Users struggling to find records or complaining about slow rendering with 1,000+ rows.
- Designing responsive table adaptations for mobile and tablet screens.

## What to Analyze

1. **Information Density**: Compact vs Standard vs Comfortable row height toggles.
2. **Fixed Elements**: Sticky table header (`position: sticky`) and sticky left identifier / right action columns.

## Purpose

Catch places where UI code uses raw/hardcoded values (hex colors, pixel spacing, arbitrary font sizes) instead of the project's established design tokens — the specific class of consistency drift that causes a design system to slowly stop being followed.

## When to Use

- The project has an established design-token system (CSS variables, a theme object, Tailwind config, etc.) and you want to check code against it.
- Reviewing new UI code for token compliance before merge.
- Auditing an existing codebase for accumulated token drift.

Requires knowing (or being told, or being able to find) the project's actual token set — this skill checks *against* an existing system, it doesn't invent one from scratch (for that, see [UI Auditor](../ui-auditor/) for general consistency without an established token baseline).

## What to Analyze