@ghostbyte/agent-docs-kit 4.0.2 → 5.0.0

package/content/engineering/01-query-performance.md

@@ -1,48 +1,38 @@
 # Query Performance & Slow Query Diagnosis
 
-# Engineering Topic 1: Query Performance & Slow Query Diagnosis
+## Engineering Topic 1: Query Performance & Slow Query Diagnosis
 
 **When to run this:** When a query, endpoint, or report is running slower than expected, or before shipping a new query against a table that will grow.
 
 **Goal of this pass:** Work through the standard diagnostic order for a slow query instead of guessing at fixes — read the plan first, fix the cheapest thing, and don't reach for denormalization until indexing is exhausted.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
-`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
-testing — there's no severity rating, and "Fail" isn't the right framing.
-Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
-Should adopt, or Not applicable.
+Use each stable practice ID in a generated engineering worksheet. Record concrete evidence and choose Applied, Partial, Recommended, Unverified, or N/A. Preserve each dated worksheet as review history.
 
 ## Wrap-up
 
 - This isn't a gate — nothing here blocks a release the way
-  Critical/High security items in `../../security-gate/phases/` do.
+  Critical/High security items in security phase reviews do.
 - Total concepts in this topic: 10
 - Useful as an onboarding read-through, a periodic self-audit, or context
   to hand an agent before it reviews related code.
 
 ---
 
-# Concepts — Topic 1: Query Performance & Slow Query Diagnosis
+## Concepts — Topic 1: Query Performance & Slow Query Diagnosis
 
-Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a pass.
+Use the applicable practices below to populate the worksheet findings table.
 
-| # | Concept | Why it matters | Self-check |
+| Practice ID | Practice | Why it matters | Evidence question |
 |---|---|---|---|
-| 1 | Start with the explain plan | Reveals whether the DB is scanning, sorting, or joining in a way that doesn't match intent — guessing at fixes without this wastes time. | Have you run EXPLAIN (or EXPLAIN ANALYZE) on the slow query and read where the time actually goes? |
-| 2 | Add the missing index | Full table scans get linearly worse as data grows; the right index turns O(n) into O(log n). | Does the WHERE/JOIN/ORDER BY column set have a supporting index? |
-| 3 | Stop selecting * | Pulling unused columns wastes I/O and network, and can defeat a covering index. | Does the query request only the columns actually used downstream? |
-| 4 | Fix N+1 queries | One query per row in a loop turns a single request into hundreds; batching/joining collapses it back to one or few. | Does any code path issue a query inside a loop over another query's results? |
-| 5 | Use a covering index | An index that includes all selected columns lets the DB answer from the index alone, skipping the table lookup. | For hot read queries, does the index include every column the query selects? |
-| 6 | Cache repeated queries | Identical, expensive, low-volatility queries don't need to hit the DB every time. | Are the same expensive read queries re-run frequently with unchanged results, and if so, are they cached? |
-| 7 | Prune partitions | Partition pruning lets the DB skip irrelevant partitions entirely instead of scanning the whole table. | For large time-series/partitioned tables, does the query filter on the partition key so pruning can kick in? |
-| 8 | Denormalize for reads | Trading write complexity/redundancy for fewer joins can be the right call once indexing alone isn't enough. | Has indexing been exhausted before reaching for denormalization, and is the redundancy kept in sync deliberately? |
-| 9 | Batch your writes | Many small write round-trips cost more in overhead than one larger batched write. | Are writes that happen together (e.g. in a loop or transaction) batched instead of issued one at a time? |
-| 10 | Update table statistics | A stale planner (out-of-date row-count/distribution stats) can pick a bad plan even with the right indexes present. | Are table statistics refreshed on a schedule (ANALYZE / equivalent), especially after large data changes? |
+| ENG-01-01 | Start with the explain plan | Reveals whether the DB is scanning, sorting, or joining in a way that doesn't match intent — guessing at fixes without this wastes time. | Have you run EXPLAIN (or EXPLAIN ANALYZE) on the slow query and read where the time actually goes? |
+| ENG-01-02 | Add the missing index | Full table scans get linearly worse as data grows; the right index turns O(n) into O(log n). | Does the WHERE/JOIN/ORDER BY column set have a supporting index? |
+| ENG-01-03 | Stop selecting * | Pulling unused columns wastes I/O and network, and can defeat a covering index. | Does the query request only the columns actually used downstream? |
+| ENG-01-04 | Fix N+1 queries | One query per row in a loop turns a single request into hundreds; batching/joining collapses it back to one or few. | Does any code path issue a query inside a loop over another query's results? |
+| ENG-01-05 | Use a covering index | An index that includes all selected columns lets the DB answer from the index alone, skipping the table lookup. | For hot read queries, does the index include every column the query selects? |
+| ENG-01-06 | Cache repeated queries | Identical, expensive, low-volatility queries don't need to hit the DB every time. | Are the same expensive read queries re-run frequently with unchanged results, and if so, are they cached? |
+| ENG-01-07 | Prune partitions | Partition pruning lets the DB skip irrelevant partitions entirely instead of scanning the whole table. | For large time-series/partitioned tables, does the query filter on the partition key so pruning can kick in? |
+| ENG-01-08 | Denormalize for reads | Trading write complexity/redundancy for fewer joins can be the right call once indexing alone isn't enough. | Has indexing been exhausted before reaching for denormalization, and is the redundancy kept in sync deliberately? |
+| ENG-01-09 | Batch your writes | Many small write round-trips cost more in overhead than one larger batched write. | Are writes that happen together (e.g. in a loop or transaction) batched instead of issued one at a time? |
+| ENG-01-10 | Update table statistics | A stale planner (out-of-date row-count/distribution stats) can pick a bad plan even with the right indexes present. | Are table statistics refreshed on a schedule (ANALYZE / equivalent), especially after large data changes? |

package/content/engineering/02-networking-fundamentals.md

@@ -1,48 +1,38 @@
 # Networking Fundamentals
 
-# Engineering Topic 2: Networking Fundamentals
+## Engineering Topic 2: Networking Fundamentals
 
 **When to run this:** When debugging connectivity, latency, or TLS issues, or before making infra decisions (load balancer, CDN, multi-region) that depend on understanding the network path.
 
 **Goal of this pass:** Confirm the team can reason about what happens between a client request and a server response — not memorize trivia, but recognize which layer a given production issue actually lives in.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
-`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
-testing — there's no severity rating, and "Fail" isn't the right framing.
-Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
-Should adopt, or Not applicable.
+Use each stable practice ID in a generated engineering worksheet. Record concrete evidence and choose Applied, Partial, Recommended, Unverified, or N/A. Preserve each dated worksheet as review history.
 
 ## Wrap-up
 
 - This isn't a gate — nothing here blocks a release the way
-  Critical/High security items in `../../security-gate/phases/` do.
+  Critical/High security items in security phase reviews do.
 - Total concepts in this topic: 10
 - Useful as an onboarding read-through, a periodic self-audit, or context
   to hand an agent before it reviews related code.
 
 ---
 
-# Concepts — Topic 2: Networking Fundamentals
+## Concepts — Topic 2: Networking Fundamentals
 
-Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a pass.
+Use the applicable practices below to populate the worksheet findings table.
 
-| # | Concept | Why it matters | Self-check |
+| Practice ID | Practice | Why it matters | Evidence question |
 |---|---|---|---|
-| 1 | DNS resolution | Wrong TTLs or stale records cause outages/slow failover that look like application bugs. | Do you know your DNS TTLs and what happens on a DNS provider outage or a failed cutover? |
-| 2 | TCP handshake | SYN/SYN-ACK/ACK latency adds to every new connection; connection reuse avoids paying it repeatedly. | Are connections being reused (keep-alive/pooling) where the handshake cost matters? |
-| 3 | TLS handshake | Adds round trips and CPU cost on top of TCP; session resumption and TLS version choice affect both. | Is TLS session resumption enabled, and is the minimum TLS version intentionally set? |
-| 4 | NAT | Explains why a server sees one client IP for many real users, and why some P2P/inbound-connection patterns don't work as expected. | Does any rate-limiting or per-client logic depend on client IP, and does it account for NAT'd clients sharing an IP? |
-| 5 | Load balancer types | L4 vs L7 balancers differ in what they can inspect and route on (raw TCP vs HTTP headers/paths). | Does the current load balancer type actually support the routing/health-check behavior the app needs? |
-| 6 | CDN edge caching | Wrong cache-control headers cause either stale content served for too long or origin overload from no caching at all. | Are cache-control/CDN cache-key rules deliberately set per route, not left at CDN defaults? |
-| 7 | Packet loss & retransmit | Retransmits show up as latency and timeouts that look application-side but are actually network-layer. | When debugging intermittent slowness, has packet loss been ruled out before blaming application code? |
-| 8 | MTU / fragmentation | Oversized packets get fragmented or dropped, which shows up as weird partial-failure behavior, especially over VPNs/tunnels. | Has MTU mismatch been considered for any VPN, tunnel, or container network path in play? |
-| 9 | Keep-alive | Persistent connections avoid the handshake cost per request but tie up server resources if left open too long. | Are keep-alive timeouts tuned deliberately on both client and server, not left at framework defaults? |
-| 10 | BGP routing | Explains internet-scale outages and route leaks — usually outside your control, but recognizable when it's the actual cause. | When a broad, upstream-looking outage occurs, is BGP/routing considered as a possible cause rather than assumed to be your infra? |
+| ENG-02-01 | DNS resolution | Wrong TTLs or stale records cause outages/slow failover that look like application bugs. | Do you know your DNS TTLs and what happens on a DNS provider outage or a failed cutover? |
+| ENG-02-02 | TCP handshake | SYN/SYN-ACK/ACK latency adds to every new connection; connection reuse avoids paying it repeatedly. | Are connections being reused (keep-alive/pooling) where the handshake cost matters? |
+| ENG-02-03 | TLS handshake | Adds round trips and CPU cost on top of TCP; session resumption and TLS version choice affect both. | Is TLS session resumption enabled, and is the minimum TLS version intentionally set? |
+| ENG-02-04 | NAT | Explains why a server sees one client IP for many real users, and why some P2P/inbound-connection patterns don't work as expected. | Does any rate-limiting or per-client logic depend on client IP, and does it account for NAT'd clients sharing an IP? |
+| ENG-02-05 | Load balancer types | L4 vs L7 balancers differ in what they can inspect and route on (raw TCP vs HTTP headers/paths). | Does the current load balancer type actually support the routing/health-check behavior the app needs? |
+| ENG-02-06 | CDN edge caching | Wrong cache-control headers cause either stale content served for too long or origin overload from no caching at all. | Are cache-control/CDN cache-key rules deliberately set per route, not left at CDN defaults? |
+| ENG-02-07 | Packet loss & retransmit | Retransmits show up as latency and timeouts that look application-side but are actually network-layer. | When debugging intermittent slowness, has packet loss been ruled out before blaming application code? |
+| ENG-02-08 | MTU / fragmentation | Oversized packets get fragmented or dropped, which shows up as weird partial-failure behavior, especially over VPNs/tunnels. | Has MTU mismatch been considered for any VPN, tunnel, or container network path in play? |
+| ENG-02-09 | Keep-alive | Persistent connections avoid the handshake cost per request but tie up server resources if left open too long. | Are keep-alive timeouts tuned deliberately on both client and server, not left at framework defaults? |
+| ENG-02-10 | BGP routing | Explains internet-scale outages and route leaks — usually outside your control, but recognizable when it's the actual cause. | When a broad, upstream-looking outage occurs, is BGP/routing considered as a possible cause rather than assumed to be your infra? |

package/content/engineering/03-rate-limiting-algorithms.md

@@ -1,48 +1,38 @@
 # Rate Limiting Algorithm Choices
 
-# Engineering Topic 3: Rate Limiting Algorithm Choices
+## Engineering Topic 3: Rate Limiting Algorithm Choices
 
-**When to run this:** When designing or reviewing a rate limiter — this is a companion to the security check in security-gate/SECURITY_CHECKLIST.md → 01_API_Security/01_rate_limiting.md, focused on picking the right algorithm rather than confirming a limiter exists.
+**When to run this:** When designing or reviewing a rate limiter. This topic focuses on selecting the appropriate algorithm; the API security phase separately verifies that protective limits exist and are effective.
 
 **Goal of this pass:** Make sure the chosen algorithm actually matches the traffic pattern being protected against, instead of defaulting to whatever's easiest to implement.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
-`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
-testing — there's no severity rating, and "Fail" isn't the right framing.
-Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
-Should adopt, or Not applicable.
+Use each stable practice ID in a generated engineering worksheet. Record concrete evidence and choose Applied, Partial, Recommended, Unverified, or N/A. Preserve each dated worksheet as review history.
 
 ## Wrap-up
 
 - This isn't a gate — nothing here blocks a release the way
-  Critical/High security items in `../../security-gate/phases/` do.
+  Critical/High security items in security phase reviews do.
 - Total concepts in this topic: 10
 - Useful as an onboarding read-through, a periodic self-audit, or context
   to hand an agent before it reviews related code.
 
 ---
 
-# Concepts — Topic 3: Rate Limiting Algorithm Choices
+## Concepts — Topic 3: Rate Limiting Algorithm Choices
 
-Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a pass.
+Use the applicable practices below to populate the worksheet findings table.
 
-| # | Concept | Why it matters | Self-check |
+| Practice ID | Practice | Why it matters | Evidence question |
 |---|---|---|---|
-| 1 | Fixed window | Simple to implement but allows a burst of 2x the limit right at the window boundary. | If fixed window is used, is the boundary-burst behavior acceptable for this endpoint? |
-| 2 | Sliding window log | Precise (tracks every request timestamp) but memory-heavy at scale. | If precision matters and volume is low/medium, is sliding window log a better fit than fixed window? |
-| 3 | Sliding window counter | Approximates the sliding log with much less memory by weighting two adjacent fixed windows. | For high-volume endpoints needing better accuracy than fixed window, is sliding window counter being used instead of the log variant? |
-| 4 | Token bucket | Allows controlled bursts up to the bucket size while enforcing a steady refill rate — good for bursty-but-bounded traffic. | Does the traffic pattern need to allow short bursts, and if so, is token bucket the chosen algorithm? |
-| 5 | Leaky bucket | Smooths bursty input into a constant output rate — good for protecting a downstream system that can't handle spikes at all. | Is there a downstream system that needs a strictly constant request rate, and if so, is leaky bucket used to enforce it? |
-| 6 | Distributed rate limiting | A per-instance limiter is meaningless behind a load balancer with multiple app servers — limits get multiplied by instance count. | If the app runs on more than one instance, is the rate limit state shared (e.g. via Redis) rather than per-instance? |
-| 7 | Client-side throttling | Reduces wasted requests and improves UX, but is never sufficient alone since a client can be bypassed or malicious. | Does the client throttle its own request rate, and is server-side enforcement still present as the actual control? |
-| 8 | Adaptive rate limiting | Static limits can be too strict in quiet periods or too loose under load; adaptive limits adjust to current system health. | Does the limiter adjust based on current load/error rate, or is it a single static number regardless of system state? |
-| 9 | Concurrency limiting | Limits in-flight requests, not just requests-per-second — protects against slow requests piling up and exhausting resources. | Is there a cap on concurrent in-flight requests per client, separate from the requests-per-second limit? |
-| 10 | Back pressure | Signals upstream to slow down instead of silently dropping or queuing indefinitely when a system is overloaded. | When downstream capacity is exceeded, does the system push back (429/503, queue limits) rather than accepting unbounded work? |
+| ENG-03-01 | Fixed window | Simple to implement but allows a burst of 2x the limit right at the window boundary. | If fixed window is used, is the boundary-burst behavior acceptable for this endpoint? |
+| ENG-03-02 | Sliding window log | Precise (tracks every request timestamp) but memory-heavy at scale. | If precision matters and volume is low/medium, is sliding window log a better fit than fixed window? |
+| ENG-03-03 | Sliding window counter | Approximates the sliding log with much less memory by weighting two adjacent fixed windows. | For high-volume endpoints needing better accuracy than fixed window, is sliding window counter being used instead of the log variant? |
+| ENG-03-04 | Token bucket | Allows controlled bursts up to the bucket size while enforcing a steady refill rate — good for bursty-but-bounded traffic. | Does the traffic pattern need to allow short bursts, and if so, is token bucket the chosen algorithm? |
+| ENG-03-05 | Leaky bucket | Smooths bursty input into a constant output rate — good for protecting a downstream system that can't handle spikes at all. | Is there a downstream system that needs a strictly constant request rate, and if so, is leaky bucket used to enforce it? |
+| ENG-03-06 | Distributed rate limiting | A per-instance limiter is meaningless behind a load balancer with multiple app servers — limits get multiplied by instance count. | If the app runs on more than one instance, is the rate limit state shared (e.g. via Redis) rather than per-instance? |
+| ENG-03-07 | Client-side throttling | Reduces wasted requests and improves UX, but is never sufficient alone since a client can be bypassed or malicious. | Does the client throttle its own request rate, and is server-side enforcement still present as the actual control? |
+| ENG-03-08 | Adaptive rate limiting | Static limits can be too strict in quiet periods or too loose under load; adaptive limits adjust to current system health. | Does the limiter adjust based on current load/error rate, or is it a single static number regardless of system state? |
+| ENG-03-09 | Concurrency limiting | Limits in-flight requests, not just requests-per-second — protects against slow requests piling up and exhausting resources. | Is there a cap on concurrent in-flight requests per client, separate from the requests-per-second limit? |
+| ENG-03-10 | Back pressure | Signals upstream to slow down instead of silently dropping or queuing indefinitely when a system is overloaded. | When downstream capacity is exceeded, does the system push back (429/503, queue limits) rather than accepting unbounded work? |

package/content/engineering/04-production-debugging.md

@@ -1,48 +1,38 @@
 # Production Debugging
 
-# Engineering Topic 4: Debugging Production Issues
+## Engineering Topic 4: Debugging Production Issues
 
 **When to run this:** Before an incident happens — this is about having the right tooling and habits in place, not what to do during a live fire.
 
 **Goal of this pass:** Confirm the team has the observability primitives needed to actually diagnose a production issue quickly, not just react to alerts.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
-`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
-testing — there's no severity rating, and "Fail" isn't the right framing.
-Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
-Should adopt, or Not applicable.
+Use each stable practice ID in a generated engineering worksheet. Record concrete evidence and choose Applied, Partial, Recommended, Unverified, or N/A. Preserve each dated worksheet as review history.
 
 ## Wrap-up
 
 - This isn't a gate — nothing here blocks a release the way
-  Critical/High security items in `../../security-gate/phases/` do.
+  Critical/High security items in security phase reviews do.
 - Total concepts in this topic: 10
 - Useful as an onboarding read-through, a periodic self-audit, or context
   to hand an agent before it reviews related code.
 
 ---
 
-# Concepts — Topic 4: Debugging Production Issues
+## Concepts — Topic 4: Debugging Production Issues
 
-Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a pass.
+Use the applicable practices below to populate the worksheet findings table.
 
-| # | Concept | Why it matters | Self-check |
+| Practice ID | Practice | Why it matters | Evidence question |
 |---|---|---|---|
-| 1 | Correlation IDs | Without a shared ID, tracing one user's request across multiple services means grepping logs by timestamp and guessing. | Does every request get a correlation/request ID that's propagated across all services it touches and included in every log line? |
-| 2 | Distributed tracing | Shows exactly where time is spent across a multi-service call chain — impossible to reconstruct from logs alone at scale. | Is distributed tracing (e.g. OpenTelemetry) instrumented across service boundaries? |
-| 3 | Feature flag rollback | Turning off a bad feature via flag is faster and safer than a code rollback/redeploy under incident pressure. | Can the riskiest recent features be disabled via flag without a deploy? |
-| 4 | Canary analysis | Rolling out to a small subset first catches regressions before they hit 100% of traffic. | Are risky changes rolled out to a canary/subset with automated comparison against the baseline before full rollout? |
-| 5 | Replay traffic | Re-running real production requests against a fix confirms it actually resolves the issue, not just a synthetic test case. | Is there a way to replay real production traffic (or a sample) against a candidate fix before it ships? |
-| 6 | Heap dumps | A heap dump is often the only way to root-cause a memory leak instead of guessing from symptoms. | Is heap-dump capture available (manually or via crash trigger) for services with memory-related symptoms? |
-| 7 | Chaos testing | Deliberately injecting failure in a controlled way surfaces weaknesses before real, uncontrolled failure does. | Has chaos testing (killing instances, injecting latency/errors) been run against critical paths? |
-| 8 | Synthetic monitoring | Catches outages and regressions from the outside, the way a real user would experience them, independent of internal metrics. | Are synthetic checks running against critical user journeys from outside the infrastructure? |
-| 9 | Error budgets | Gives a quantified, agreed-upon threshold for how much unreliability is acceptable, so incident response isn't a judgment call every time. | Is there an agreed error budget per service, and does exceeding it trigger a defined response (e.g. freeze on new features)? |
-| 10 | Postmortems | Without a blameless, written record, the same class of incident tends to recur because the lesson isn't institutionalized. | Does every significant incident get a blameless postmortem with concrete follow-up actions that are actually tracked to completion? |
+| ENG-04-01 | Correlation IDs | Without a shared ID, tracing one user's request across multiple services means grepping logs by timestamp and guessing. | Does every request get a correlation/request ID that's propagated across all services it touches and included in every log line? |
+| ENG-04-02 | Distributed tracing | Shows exactly where time is spent across a multi-service call chain — impossible to reconstruct from logs alone at scale. | Is distributed tracing (e.g. OpenTelemetry) instrumented across service boundaries? |
+| ENG-04-03 | Feature flag rollback | Turning off a bad feature via flag is faster and safer than a code rollback/redeploy under incident pressure. | Can the riskiest recent features be disabled via flag without a deploy? |
+| ENG-04-04 | Canary analysis | Rolling out to a small subset first catches regressions before they hit 100% of traffic. | Are risky changes rolled out to a canary/subset with automated comparison against the baseline before full rollout? |
+| ENG-04-05 | Replay traffic | Re-running real production requests against a fix confirms it actually resolves the issue, not just a synthetic test case. | Is there a way to replay real production traffic (or a sample) against a candidate fix before it ships? |
+| ENG-04-06 | Heap dumps | A heap dump is often the only way to root-cause a memory leak instead of guessing from symptoms. | Is heap-dump capture available (manually or via crash trigger) for services with memory-related symptoms? |
+| ENG-04-07 | Chaos testing | Deliberately injecting failure in a controlled way surfaces weaknesses before real, uncontrolled failure does. | Has chaos testing (killing instances, injecting latency/errors) been run against critical paths? |
+| ENG-04-08 | Synthetic monitoring | Catches outages and regressions from the outside, the way a real user would experience them, independent of internal metrics. | Are synthetic checks running against critical user journeys from outside the infrastructure? |
+| ENG-04-09 | Error budgets | Gives a quantified, agreed-upon threshold for how much unreliability is acceptable, so incident response isn't a judgment call every time. | Is there an agreed error budget per service, and does exceeding it trigger a defined response (e.g. freeze on new features)? |
+| ENG-04-10 | Postmortems | Without a blameless, written record, the same class of incident tends to recur because the lesson isn't institutionalized. | Does every significant incident get a blameless postmortem with concrete follow-up actions that are actually tracked to completion? |

package/content/engineering/05-code-review-practices.md

@@ -1,48 +1,38 @@
 # Code Review Practices
 
-# Engineering Topic 5: Code Review Practices
+## Engineering Topic 5: Code Review Practices
 
 **When to run this:** Ongoing — use this to periodically check whether the team's actual review habits match its stated process, not just once.
 
 **Goal of this pass:** Keep review effective and fast rather than either a rubber stamp or a bottleneck.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
-`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
-testing — there's no severity rating, and "Fail" isn't the right framing.
-Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
-Should adopt, or Not applicable.
+Use each stable practice ID in a generated engineering worksheet. Record concrete evidence and choose Applied, Partial, Recommended, Unverified, or N/A. Preserve each dated worksheet as review history.
 
 ## Wrap-up
 
 - This isn't a gate — nothing here blocks a release the way
-  Critical/High security items in `../../security-gate/phases/` do.
+  Critical/High security items in security phase reviews do.
 - Total concepts in this topic: 10
 - Useful as an onboarding read-through, a periodic self-audit, or context
   to hand an agent before it reviews related code.
 
 ---
 
-# Concepts — Topic 5: Code Review Practices
+## Concepts — Topic 5: Code Review Practices
 
-Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a pass.
+Use the applicable practices below to populate the worksheet findings table.
 
-| # | Concept | Why it matters | Self-check |
+| Practice ID | Practice | Why it matters | Evidence question |
 |---|---|---|---|
-| 1 | Small PRs | Large PRs get worse review (reviewers skim or rubber-stamp) and take longer to land. | Is there a rough size norm for PRs, and are oversized PRs flagged for splitting? |
-| 2 | Clear description | A reviewer without context re-derives the 'why' from the diff alone, which is slower and more error-prone than being told. | Does every PR description explain what changed and why, not just restate the diff? |
-| 3 | Constructive feedback | Feedback that reads as personal or vague either gets ignored or damages the reviewer/author relationship over time. | Is feedback phrased around the code/tradeoff rather than the author, with a suggested direction, not just a criticism? |
-| 4 | Nitpick vs blocker | Without this distinction, minor style opinions can block a merge as if they were correctness issues. | Are non-blocking comments explicitly labeled (e.g. 'nit:') so the author knows what's optional vs required? |
-| 5 | Fast turnaround | A PR that sits for days loses context for both author and reviewer and blocks downstream work. | Is there a target turnaround time for first review, and is it generally being met? |
-| 6 | Automated checks first | Humans shouldn't spend review time on things a linter/CI can catch automatically. | Do lint, format, and test checks run and pass before a human reviews the PR? |
-| 7 | Context before code | Reviewing code without understanding the surrounding system leads to reviews that miss integration-level problems. | Does the reviewer understand the relevant part of the system before diving into line-by-line comments? |
-| 8 | Approve vs request changes | Conflating 'I have a question' with 'this is blocked' slows things down or sends mixed signals. | Is the approve/comment/request-changes distinction used deliberately, not defaulted to whichever is habit? |
-| 9 | Self-review first | Authors catch a meaningful fraction of their own issues by re-reading the diff before asking someone else to. | Does the author review their own diff (and leave self-notes where useful) before requesting review? |
-| 10 | Learning from reviews | Review comments that aren't retained just repeat themselves across future PRs instead of becoming shared knowledge. | Do recurring review comments get turned into a lint rule, style-guide entry, or documented convention? |
+| ENG-05-01 | Small PRs | Large PRs get worse review (reviewers skim or rubber-stamp) and take longer to land. | Is there a rough size norm for PRs, and are oversized PRs flagged for splitting? |
+| ENG-05-02 | Clear description | A reviewer without context re-derives the 'why' from the diff alone, which is slower and more error-prone than being told. | Does every PR description explain what changed and why, not just restate the diff? |
+| ENG-05-03 | Constructive feedback | Feedback that reads as personal or vague either gets ignored or damages the reviewer/author relationship over time. | Is feedback phrased around the code/tradeoff rather than the author, with a suggested direction, not just a criticism? |
+| ENG-05-04 | Nitpick vs blocker | Without this distinction, minor style opinions can block a merge as if they were correctness issues. | Are non-blocking comments explicitly labeled (e.g. 'nit:') so the author knows what's optional vs required? |
+| ENG-05-05 | Fast turnaround | A PR that sits for days loses context for both author and reviewer and blocks downstream work. | Is there a target turnaround time for first review, and is it generally being met? |
+| ENG-05-06 | Automated checks first | Humans shouldn't spend review time on things a linter/CI can catch automatically. | Do lint, format, and test checks run and pass before a human reviews the PR? |
+| ENG-05-07 | Context before code | Reviewing code without understanding the surrounding system leads to reviews that miss integration-level problems. | Does the reviewer understand the relevant part of the system before diving into line-by-line comments? |
+| ENG-05-08 | Approve vs request changes | Conflating 'I have a question' with 'this is blocked' slows things down or sends mixed signals. | Is the approve/comment/request-changes distinction used deliberately, not defaulted to whichever is habit? |
+| ENG-05-09 | Self-review first | Authors catch a meaningful fraction of their own issues by re-reading the diff before asking someone else to. | Does the author review their own diff (and leave self-notes where useful) before requesting review? |
+| ENG-05-10 | Learning from reviews | Review comments that aren't retained just repeat themselves across future PRs instead of becoming shared knowledge. | Do recurring review comments get turned into a lint rule, style-guide entry, or documented convention? |

package/content/engineering/06-data-modeling.md

@@ -1,48 +1,38 @@
 # Data Modeling
 
-# Engineering Topic 6: Data Modeling Concepts
+## Engineering Topic 6: Data Modeling Concepts
 
 **When to run this:** When designing a new schema, adding a table/relationship to an existing one, or reviewing a migration before it ships.
 
 **Goal of this pass:** Confirm the schema decisions are deliberate — the right relationship type, the right key strategy, the right precision — rather than whatever the ORM defaulted to.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
-`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
-testing — there's no severity rating, and "Fail" isn't the right framing.
-Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
-Should adopt, or Not applicable.
+Use each stable practice ID in a generated engineering worksheet. Record concrete evidence and choose Applied, Partial, Recommended, Unverified, or N/A. Preserve each dated worksheet as review history.
 
 ## Wrap-up
 
 - This isn't a gate — nothing here blocks a release the way
-  Critical/High security items in `../../security-gate/phases/` do.
+  Critical/High security items in security phase reviews do.
 - Total concepts in this topic: 10
 - Useful as an onboarding read-through, a periodic self-audit, or context
   to hand an agent before it reviews related code.
 
 ---
 
-# Concepts — Topic 6: Data Modeling Concepts
+## Concepts — Topic 6: Data Modeling Concepts
 
-Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a pass.
+Use the applicable practices below to populate the worksheet findings table.
 
-| # | Concept | Why it matters | Self-check |
+| Practice ID | Practice | Why it matters | Evidence question |
 |---|---|---|---|
-| 1 | Primary vs foreign keys | Gets the basic referential integrity of the schema right; missing FK constraints let orphaned/inconsistent data accumulate silently. | Does every relationship that should be enforced have an actual FK constraint, not just an implied convention? |
-| 2 | One-to-many | The most common relationship shape; modeling it as many-to-many or vice versa causes either data duplication or missing constraints. | For each relationship, has one-to-many vs many-to-many actually been verified against real-world cardinality, not assumed? |
-| 3 | Many-to-many | Requires a join table; skipping it (e.g. storing a comma-separated list) breaks referential integrity and queryability. | Are many-to-many relationships modeled with a proper join table rather than a denormalized list column? |
-| 4 | Composite keys | Sometimes the natural key is a combination of columns, not a synthetic ID — forcing a synthetic key can hide a real uniqueness constraint. | Where a natural composite key exists (e.g. user_id + role_id), is it enforced as a unique constraint even if a synthetic PK is also used? |
-| 5 | Soft deletes | A `deleted_at` column preserves history/auditability but means every query must remember to filter it, or leaked 'deleted' data appears. | If soft deletes are used, do all reads consistently filter them out (e.g. via a default scope), and is that not forgotten in raw queries? |
-| 6 | Polymorphic associations | Lets one table reference multiple other table types, but sacrifices FK constraint enforcement at the DB level — a known tradeoff, not a free pattern. | Where a polymorphic association is used, was that tradeoff (no DB-level FK) made deliberately, with integrity checks handled elsewhere? |
-| 7 | Enum vs lookup table | A hardcoded enum is faster to query but requires a migration/deploy to add a value; a lookup table is more flexible but adds a join. | Was the enum-vs-lookup-table choice made based on how often the value set changes, not just habit? |
-| 8 | Audit columns | Without created_at/updated_at/created_by-style columns, debugging 'when did this change and who did it' becomes guesswork. | Do tables that matter for debugging/compliance have consistent audit columns? |
-| 9 | Schema migrations | Migrations that aren't reversible or aren't tested against production-scale data can cause downtime or data loss when they run for real. | Are migrations reviewed for reversibility and tested against realistic data volume before running on production? |
-| 10 | Precision & data types | Using float for money, or too-small an int type for a growing counter, causes rounding errors or overflow that surface much later. | Are numeric types chosen deliberately (e.g. decimal for currency, right-sized int for counters expected to grow)? |
+| ENG-06-01 | Primary vs foreign keys | Gets the basic referential integrity of the schema right; missing FK constraints let orphaned/inconsistent data accumulate silently. | Does every relationship that should be enforced have an actual FK constraint, not just an implied convention? |
+| ENG-06-02 | One-to-many | The most common relationship shape; modeling it as many-to-many or vice versa causes either data duplication or missing constraints. | For each relationship, has one-to-many vs many-to-many actually been verified against real-world cardinality, not assumed? |
+| ENG-06-03 | Many-to-many | Requires a join table; skipping it (e.g. storing a comma-separated list) breaks referential integrity and queryability. | Are many-to-many relationships modeled with a proper join table rather than a denormalized list column? |
+| ENG-06-04 | Composite keys | Sometimes the natural key is a combination of columns, not a synthetic ID — forcing a synthetic key can hide a real uniqueness constraint. | Where a natural composite key exists (e.g. user_id + role_id), is it enforced as a unique constraint even if a synthetic PK is also used? |
+| ENG-06-05 | Soft deletes | A `deleted_at` column preserves history/auditability but means every query must remember to filter it, or leaked 'deleted' data appears. | If soft deletes are used, do all reads consistently filter them out (e.g. via a default scope), and is that not forgotten in raw queries? |
+| ENG-06-06 | Polymorphic associations | Lets one table reference multiple other table types, but sacrifices FK constraint enforcement at the DB level — a known tradeoff, not a free pattern. | Where a polymorphic association is used, was that tradeoff (no DB-level FK) made deliberately, with integrity checks handled elsewhere? |
+| ENG-06-07 | Enum vs lookup table | A hardcoded enum is faster to query but requires a migration/deploy to add a value; a lookup table is more flexible but adds a join. | Was the enum-vs-lookup-table choice made based on how often the value set changes, not just habit? |
+| ENG-06-08 | Audit columns | Without created_at/updated_at/created_by-style columns, debugging 'when did this change and who did it' becomes guesswork. | Do tables that matter for debugging/compliance have consistent audit columns? |
+| ENG-06-09 | Schema migrations | Migrations that aren't reversible or aren't tested against production-scale data can cause downtime or data loss when they run for real. | Are migrations reviewed for reversibility and tested against realistic data volume before running on production? |
+| ENG-06-10 | Precision & data types | Using float for money, or too-small an int type for a growing counter, causes rounding errors or overflow that surface much later. | Are numeric types chosen deliberately (e.g. decimal for currency, right-sized int for counters expected to grow)? |

package/content/engineering/07-cloud-cost-saving.md

@@ -1,48 +1,38 @@
 # Cloud Cost Saving
 
-# Engineering Topic 7: Cloud Cost-Saving Techniques
+## Engineering Topic 7: Cloud Cost-Saving Techniques
 
 **When to run this:** During a cost review, before scaling up infrastructure, or when a cloud bill increase needs investigating.
 
 **Goal of this pass:** Work through the standard cost levers systematically instead of just cutting the first expensive-looking line item.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
-`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
-testing — there's no severity rating, and "Fail" isn't the right framing.
-Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
-Should adopt, or Not applicable.
+Use each stable practice ID in a generated engineering worksheet. Record concrete evidence and choose Applied, Partial, Recommended, Unverified, or N/A. Preserve each dated worksheet as review history.
 
 ## Wrap-up
 
 - This isn't a gate — nothing here blocks a release the way
-  Critical/High security items in `../../security-gate/phases/` do.
+  Critical/High security items in security phase reviews do.
 - Total concepts in this topic: 10
 - Useful as an onboarding read-through, a periodic self-audit, or context
   to hand an agent before it reviews related code.
 
 ---
 
-# Concepts — Topic 7: Cloud Cost-Saving Techniques
+## Concepts — Topic 7: Cloud Cost-Saving Techniques
 
-Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a pass.
+Use the applicable practices below to populate the worksheet findings table.
 
-| # | Concept | Why it matters | Self-check |
+| Practice ID | Practice | Why it matters | Evidence question |
 |---|---|---|---|
-| 1 | Spot instances | Substantially cheaper than on-demand, but can be reclaimed with short notice — only right for interruption-tolerant workloads. | Are interruption-tolerant workloads (batch jobs, stateless workers) running on spot instead of on-demand? |
-| 2 | Autoscaling | Paying for peak capacity 24/7 wastes money during predictable low-traffic periods. | Does capacity actually scale down during known low-traffic periods, not just scale up under load? |
-| 3 | Reserved capacity | Committing to steady-state baseline load ahead of time is cheaper than paying on-demand rates for it continuously. | Has the stable, predictable-load portion of infrastructure been covered by reserved/committed-use pricing? |
-| 4 | Right-sizing | Over-provisioned instances (low CPU/memory utilization) are a direct, ongoing waste that compounds over time. | Have instance sizes been checked against actual utilization recently, not just set once at launch and left alone? |
-| 5 | Storage tiering | Infrequently accessed data doesn't need to sit on the most expensive, fastest storage tier. | Is cold/infrequently-accessed data moved to a cheaper storage tier rather than left on the default hot tier? |
-| 6 | CDN offloading | Serving static/cacheable content from origin instead of a CDN costs more in bandwidth and origin load. | Is static and cacheable content served from a CDN rather than hitting origin servers for every request? |
-| 7 | Serverless for spiky loads | Paying for always-on servers to handle infrequent, spiky workloads is wasteful compared to pay-per-invocation. | Are low-frequency, spiky workloads running serverless rather than on dedicated always-on infrastructure? |
-| 8 | Idle resource cleanup | Unattached volumes, unused load balancers, and orphaned snapshots accumulate cost silently over time. | Is there a recurring process to find and remove idle/orphaned cloud resources? |
-| 9 | Compression | Uncompressed data transfer and storage costs more in both bandwidth and storage fees than it needs to. | Is compression enabled where it's cheap to apply (asset delivery, log storage, backups)? |
-| 10 | Multi-region arbitrage | Compute/storage/egress pricing varies meaningfully by region — running in the highest-cost region without a reason is avoidable spend. | Has region choice been checked against pricing, not just picked for proximity or default? |
+| ENG-07-01 | Spot instances | Substantially cheaper than on-demand, but can be reclaimed with short notice — only right for interruption-tolerant workloads. | Are interruption-tolerant workloads (batch jobs, stateless workers) running on spot instead of on-demand? |
+| ENG-07-02 | Autoscaling | Paying for peak capacity 24/7 wastes money during predictable low-traffic periods. | Does capacity actually scale down during known low-traffic periods, not just scale up under load? |
+| ENG-07-03 | Reserved capacity | Committing to steady-state baseline load ahead of time is cheaper than paying on-demand rates for it continuously. | Has the stable, predictable-load portion of infrastructure been covered by reserved/committed-use pricing? |
+| ENG-07-04 | Right-sizing | Over-provisioned instances (low CPU/memory utilization) are a direct, ongoing waste that compounds over time. | Have instance sizes been checked against actual utilization recently, not just set once at launch and left alone? |
+| ENG-07-05 | Storage tiering | Infrequently accessed data doesn't need to sit on the most expensive, fastest storage tier. | Is cold/infrequently-accessed data moved to a cheaper storage tier rather than left on the default hot tier? |
+| ENG-07-06 | CDN offloading | Serving static/cacheable content from origin instead of a CDN costs more in bandwidth and origin load. | Is static and cacheable content served from a CDN rather than hitting origin servers for every request? |
+| ENG-07-07 | Serverless for spiky loads | Paying for always-on servers to handle infrequent, spiky workloads is wasteful compared to pay-per-invocation. | Are low-frequency, spiky workloads running serverless rather than on dedicated always-on infrastructure? |
+| ENG-07-08 | Idle resource cleanup | Unattached volumes, unused load balancers, and orphaned snapshots accumulate cost silently over time. | Is there a recurring process to find and remove idle/orphaned cloud resources? |
+| ENG-07-09 | Compression | Uncompressed data transfer and storage costs more in both bandwidth and storage fees than it needs to. | Is compression enabled where it's cheap to apply (asset delivery, log storage, backups)? |
+| ENG-07-10 | Multi-region arbitrage | Compute/storage/egress pricing varies meaningfully by region — running in the highest-cost region without a reason is avoidable spend. | Has region choice been checked against pricing, not just picked for proximity or default? |

package/content/engineering/08-testing-types.md

@@ -1,48 +1,38 @@
 # Testing Types
 
-# Engineering Topic 8: Types of Testing
+## Engineering Topic 8: Types of Testing
 
 **When to run this:** When designing a test strategy for a new project/feature, or auditing whether the current test suite has coverage gaps.
 
 **Goal of this pass:** Confirm the right mix of test types is in place for what's actually being built — not every project needs every type, but the choice should be deliberate.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
-`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
-testing — there's no severity rating, and "Fail" isn't the right framing.
-Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
-Should adopt, or Not applicable.
+Use each stable practice ID in a generated engineering worksheet. Record concrete evidence and choose Applied, Partial, Recommended, Unverified, or N/A. Preserve each dated worksheet as review history.
 
 ## Wrap-up
 
 - This isn't a gate — nothing here blocks a release the way
-  Critical/High security items in `../../security-gate/phases/` do.
+  Critical/High security items in security phase reviews do.
 - Total concepts in this topic: 10
 - Useful as an onboarding read-through, a periodic self-audit, or context
   to hand an agent before it reviews related code.
 
 ---
 
-# Concepts — Topic 8: Types of Testing
+## Concepts — Topic 8: Types of Testing
 
-Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a pass.
+Use the applicable practices below to populate the worksheet findings table.
 
-| # | Concept | Why it matters | Self-check |
+| Practice ID | Practice | Why it matters | Evidence question |
 |---|---|---|---|
-| 1 | Unit test | Tests one function/module in isolation — fast feedback, but doesn't catch integration problems. | Do core business-logic units have direct unit test coverage, isolated from external dependencies? |
-| 2 | Integration test | Tests that multiple components work together correctly (e.g. app + real DB) — catches what unit tests can't. | Are integration tests run against real (or realistic) dependencies, not just mocks, for critical paths? |
-| 3 | End-to-end test | Tests a full user flow through the real system — the closest simulation of actual usage, but slow and more brittle. | Do the most critical user journeys have E2E coverage, kept to a small, high-value set rather than everything? |
-| 4 | Snapshot test | Catches unintended changes to output (UI render, API response shape) by diffing against a saved reference. | Where snapshot tests are used, are snapshots actually reviewed on change, not blindly re-approved? |
-| 5 | Contract test | Verifies that a service's API still matches what its consumers expect, without needing a full integration environment. | For services with external consumers, are contract tests in place to catch breaking API changes before deploy? |
-| 6 | Load test | Confirms the system holds up under expected (and above-expected) traffic before it meets that traffic in production. | Has the system been load-tested at a realistic multiple of expected peak traffic? |
-| 7 | Chaos test | Confirms the system degrades gracefully under real failure conditions, not just happy-path load. | Has chaos testing been run against the critical paths (see also Debugging Production Issues)? |
-| 8 | Mutation test | Checks whether the test suite would actually catch a real bug by deliberately introducing small code mutations and seeing if tests fail. | Has mutation testing been run at least once to sanity-check that the test suite isn't just achieving coverage without catching bugs? |
-| 9 | Smoke test | A fast, shallow check that the basic system is up and functional — meant to catch catastrophic failures immediately after deploy. | Does every deploy run a fast smoke test before being considered successful? |
-| 10 | Regression test | Confirms a previously fixed bug doesn't come back — without it, the same bug can resurface silently. | Does every fixed bug get a corresponding regression test added to the suite? |
+| ENG-08-01 | Unit test | Tests one function/module in isolation — fast feedback, but doesn't catch integration problems. | Do core business-logic units have direct unit test coverage, isolated from external dependencies? |
+| ENG-08-02 | Integration test | Tests that multiple components work together correctly (e.g. app + real DB) — catches what unit tests can't. | Are integration tests run against real (or realistic) dependencies, not just mocks, for critical paths? |
+| ENG-08-03 | End-to-end test | Tests a full user flow through the real system — the closest simulation of actual usage, but slow and more brittle. | Do the most critical user journeys have E2E coverage, kept to a small, high-value set rather than everything? |
+| ENG-08-04 | Snapshot test | Catches unintended changes to output (UI render, API response shape) by diffing against a saved reference. | Where snapshot tests are used, are snapshots actually reviewed on change, not blindly re-approved? |
+| ENG-08-05 | Contract test | Verifies that a service's API still matches what its consumers expect, without needing a full integration environment. | For services with external consumers, are contract tests in place to catch breaking API changes before deploy? |
+| ENG-08-06 | Load test | Confirms the system holds up under expected (and above-expected) traffic before it meets that traffic in production. | Has the system been load-tested at a realistic multiple of expected peak traffic? |
+| ENG-08-07 | Chaos test | Confirms the system degrades gracefully under real failure conditions, not just happy-path load. | Has chaos testing been run against the critical paths (see also Debugging Production Issues)? |
+| ENG-08-08 | Mutation test | Checks whether the test suite would actually catch a real bug by deliberately introducing small code mutations and seeing if tests fail. | Has mutation testing been run at least once to sanity-check that the test suite isn't just achieving coverage without catching bugs? |
+| ENG-08-09 | Smoke test | A fast, shallow check that the basic system is up and functional — meant to catch catastrophic failures immediately after deploy. | Does every deploy run a fast smoke test before being considered successful? |
+| ENG-08-10 | Regression test | Confirms a previously fixed bug doesn't come back — without it, the same bug can resurface silently. | Does every fixed bug get a corresponding regression test added to the suite? |