@ghostbyte/agent-docs-kit 4.0.3 → 5.0.1

package/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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? |

package/skills/manage-project-quality/references/engineering-09-message-queues.md

@@ -1,48 +1,38 @@
 # Message Queues
 
-# Engineering Topic 9: Message Queue Concepts
+## Engineering Topic 9: Message Queue Concepts
 
 **When to run this:** When designing or reviewing a system that uses a message queue/event stream (Kafka, RabbitMQ, SQS, etc.) for async communication between services.
 
 **Goal of this pass:** Confirm the delivery, ordering, and failure-handling guarantees the system actually needs match what the queue setup actually provides.
 
-## 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 9: Message Queue Concepts
+## Concepts — Topic 9: Message Queue 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 | Producer / consumer | The basic decoupling pattern — getting the boundary wrong (e.g. producer waiting on consumer) defeats the purpose of using a queue at all. | Are producers and consumers actually decoupled, with the producer not blocked waiting on consumer processing? |
-| 2 | Topic + partition | Partitioning enables parallel consumption, but choosing the wrong partition key can cause hot partitions or lost ordering guarantees. | Is the partition key chosen deliberately (e.g. by entity ID) rather than defaulted, and does it avoid hot-partitioning? |
-| 3 | Consumer group | Lets multiple consumer instances share the work of one topic without processing the same message redundantly (within the group). | If there are multiple consumer instances, are they correctly grouped so work is distributed, not duplicated? |
-| 4 | At-least-once delivery | The common default guarantee — means consumers WILL sometimes see the same message twice and must handle that. | Does every consumer assume at-least-once delivery and handle duplicate messages correctly? |
-| 5 | Dead letter queue | Without one, a message that repeatedly fails processing either blocks the queue or is silently dropped. | Do failed messages, after retry limits, go to a dead letter queue instead of blocking or vanishing? |
-| 6 | Backpressure | If consumers can't keep up, the system needs a defined behavior (slow producers, buffer, drop) rather than unbounded queue growth. | Is there a defined response when consumer lag grows unbounded, rather than assuming it will always catch up? |
-| 7 | Fan-out | Delivering one message to multiple independent consumers (e.g. via separate subscriptions) needs the right topology — a single queue with one consumer group won't do it. | If multiple independent services need the same message, is the topology (e.g. separate subscriptions/topics) actually set up for fan-out? |
-| 8 | Message ordering | Most queues only guarantee order within a partition/shard, not globally — code that assumes global order will break. | Does any consumer logic assume strict global ordering, and if so, does the actual queue setup guarantee that? |
-| 9 | Idempotent consumer | Given at-least-once delivery, consumers must be able to safely process the same message twice without double-effecting (e.g. double-charging). | Is consumer processing logic idempotent (e.g. keyed on a unique message/operation ID) so redelivery is safe? |
-| 10 | Offset commit | Committing the offset too early risks losing a message if processing then fails; committing too late risks reprocessing more than necessary. | Is the offset committed only after successful processing (not before), matching the delivery guarantee the system actually needs? |
+| ENG-09-01 | Producer / consumer | The basic decoupling pattern — getting the boundary wrong (e.g. producer waiting on consumer) defeats the purpose of using a queue at all. | Are producers and consumers actually decoupled, with the producer not blocked waiting on consumer processing? |
+| ENG-09-02 | Topic + partition | Partitioning enables parallel consumption, but choosing the wrong partition key can cause hot partitions or lost ordering guarantees. | Is the partition key chosen deliberately (e.g. by entity ID) rather than defaulted, and does it avoid hot-partitioning? |
+| ENG-09-03 | Consumer group | Lets multiple consumer instances share the work of one topic without processing the same message redundantly (within the group). | If there are multiple consumer instances, are they correctly grouped so work is distributed, not duplicated? |
+| ENG-09-04 | At-least-once delivery | The common default guarantee — means consumers WILL sometimes see the same message twice and must handle that. | Does every consumer assume at-least-once delivery and handle duplicate messages correctly? |
+| ENG-09-05 | Dead letter queue | Without one, a message that repeatedly fails processing either blocks the queue or is silently dropped. | Do failed messages, after retry limits, go to a dead letter queue instead of blocking or vanishing? |
+| ENG-09-06 | Backpressure | If consumers can't keep up, the system needs a defined behavior (slow producers, buffer, drop) rather than unbounded queue growth. | Is there a defined response when consumer lag grows unbounded, rather than assuming it will always catch up? |
+| ENG-09-07 | Fan-out | Delivering one message to multiple independent consumers (e.g. via separate subscriptions) needs the right topology — a single queue with one consumer group won't do it. | If multiple independent services need the same message, is the topology (e.g. separate subscriptions/topics) actually set up for fan-out? |
+| ENG-09-08 | Message ordering | Most queues only guarantee order within a partition/shard, not globally — code that assumes global order will break. | Does any consumer logic assume strict global ordering, and if so, does the actual queue setup guarantee that? |
+| ENG-09-09 | Idempotent consumer | Given at-least-once delivery, consumers must be able to safely process the same message twice without double-effecting (e.g. double-charging). | Is consumer processing logic idempotent (e.g. keyed on a unique message/operation ID) so redelivery is safe? |
+| ENG-09-10 | Offset commit | Committing the offset too early risks losing a message if processing then fails; committing too late risks reprocessing more than necessary. | Is the offset committed only after successful processing (not before), matching the delivery guarantee the system actually needs? |

package/skills/manage-project-quality/references/engineering-10-api-design-compatibility.md

@@ -0,0 +1,14 @@
+# API Design and Compatibility
+
+Use this review before introducing or changing a public, partner, or service-to-service API.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-10-01 | Explicit contracts | Machine-readable contracts reduce client/server drift. | Is the current request, response, and error contract versioned with the implementation? |
+| ENG-10-02 | Backward compatibility | Uncoordinated breaking changes create outages. | Are removals and semantic changes gated by a documented migration window? |
+| ENG-10-03 | Consistent errors | Predictable errors make clients safer and observable. | Do errors use stable codes, safe messages, and correlation identifiers? |
+| ENG-10-04 | Idempotency | Retries must not duplicate important side effects. | Do retryable writes use an idempotency strategy with a defined lifetime? |
+| ENG-10-05 | Pagination and limits | Unbounded reads create latency and cost failures. | Are page size, ordering, cursors, and maximum limits explicit? |
+| ENG-10-06 | Deprecation telemetry | Owners need evidence before retiring a version. | Can maintainers identify remaining callers of deprecated behavior? |
+| ENG-10-07 | Contract tests | Integration assumptions should fail before deployment. | Do provider and consumer tests cover critical compatibility promises? |
+| ENG-10-08 | Safe defaults | Optional fields and defaults affect long-lived clients. | Can old clients ignore additions without changing behavior unexpectedly? |

package/skills/manage-project-quality/references/engineering-11-reliability-slos.md

@@ -0,0 +1,14 @@
+# Reliability, SLOs, and Error Budgets
+
+Use this review when defining service reliability or deciding whether delivery speed is outrunning operational health.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-11-01 | User-centered SLI | Reliability should represent user experience. | Does each indicator measure a user-visible success or latency outcome? |
+| ENG-11-02 | Achievable SLO | A target should guide decisions, not promise perfection. | Is the objective based on business need and measured historical behavior? |
+| ENG-11-03 | Error budget | Teams need a shared release-versus-reliability signal. | Is remaining error budget visible and tied to an agreed response? |
+| ENG-11-04 | Multi-window alerts | Fast and slow burns require different detection windows. | Do alerts identify material budget consumption without paging on noise? |
+| ENG-11-05 | Dependency objectives | Upstream limits constrain the service objective. | Are critical dependency availability and latency assumptions recorded? |
+| ENG-11-06 | Graceful degradation | Partial service can preserve essential workflows. | Are noncritical features shed safely when dependencies or capacity fail? |
+| ENG-11-07 | Recovery objectives | Recovery needs measurable targets. | Are RTO and RPO defined and tested for important data and workflows? |
+| ENG-11-08 | Reliability review | Objectives must evolve with product behavior. | Are SLOs reviewed after incidents and material architecture changes? |

package/skills/manage-project-quality/references/engineering-12-observability-telemetry.md

@@ -0,0 +1,14 @@
+# Observability and Telemetry
+
+Use this review when adding telemetry or when production behavior cannot be explained quickly.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-12-01 | Structured logs | Searchable fields beat unstructured narratives. | Do logs contain stable event names, severity, and correlation context? |
+| ENG-12-02 | Useful metrics | Metrics should describe demand, errors, latency, and saturation. | Can dashboards explain whether users and resources are healthy? |
+| ENG-12-03 | Distributed traces | Cross-service latency needs causal context. | Are trace identifiers propagated across supported boundaries? |
+| ENG-12-04 | Cardinality control | Unbounded labels can disable or overprice monitoring. | Are user-generated and high-cardinality values excluded from metric labels? |
+| ENG-12-05 | Sensitive-data controls | Telemetry is another data store. | Are secrets and personal data redacted before collection? |
+| ENG-12-06 | Actionable alerts | Alerts should lead to a known response. | Does every page identify impact, owner, runbook, and escalation path? |
+| ENG-12-07 | Retention and sampling | Cost controls must preserve investigation value. | Are retention and sampling choices documented by telemetry class? |
+| ENG-12-08 | Instrumentation tests | Broken telemetry can hide production failures. | Do tests verify critical events and trace propagation without asserting noise? |

package/skills/manage-project-quality/references/engineering-13-deployment-change-safety.md

@@ -0,0 +1,14 @@
+# Deployment and Change Safety
+
+Use this review for release pipelines, migrations, feature rollouts, and rollback design.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-13-01 | Small reversible changes | Small batches limit diagnosis and rollback cost. | Can the change be disabled or reverted without unrelated work? |
+| ENG-13-02 | Progressive delivery | Early signals reduce blast radius. | Is rollout staged by environment, cohort, region, or percentage? |
+| ENG-13-03 | Automated verification | Human-only checks miss repeatable regressions. | Are build, test, policy, and artifact checks required before promotion? |
+| ENG-13-04 | Migration compatibility | Code and data often deploy at different times. | Do schema changes support old and new application versions during rollout? |
+| ENG-13-05 | Health-based rollback | Rollback decisions should use defined signals. | Are stop and rollback thresholds tied to service and business health? |
+| ENG-13-06 | Artifact promotion | Rebuilding can change what was tested. | Is the verified immutable artifact promoted between environments? |
+| ENG-13-07 | Change traceability | Operators need to connect behavior to releases. | Can a running version be traced to source, build, approvals, and configuration? |
+| ENG-13-08 | Post-deployment observation | Success requires evidence after deployment. | Is there an owned observation window with a clear completion decision? |

package/skills/manage-project-quality/references/engineering-14-capacity-concurrency.md

@@ -0,0 +1,14 @@
+# Capacity, Concurrency, and Resource Management
+
+Use this review for load-sensitive services, shared resources, and systems with concurrent state changes.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-14-01 | Capacity model | Demand and limits should be explicit. | Are peak throughput, latency, storage, and headroom assumptions measured? |
+| ENG-14-02 | Bounded concurrency | Unlimited work can exhaust every dependency. | Are worker, connection, and request counts bounded at each layer? |
+| ENG-14-03 | Backpressure | Overload should be controlled rather than amplified. | Does the system reject, queue, or slow work using documented thresholds? |
+| ENG-14-04 | Timeouts and cancellation | Abandoned work should release resources. | Are timeouts budgeted end-to-end and cancellation signals propagated? |
+| ENG-14-05 | Contention testing | Shared locks and hot keys appear under load. | Do tests exercise realistic contention and skew rather than uniform traffic only? |
+| ENG-14-06 | Autoscaling signals | Scaling on the wrong signal can worsen overload. | Do scaling signals lead demand and respect dependency capacity? |
+| ENG-14-07 | Resource cleanup | Leaks turn normal operation into delayed failure. | Are connections, files, memory, and temporary objects bounded and observable? |
+| ENG-14-08 | Degradation plan | Capacity exhaustion must preserve critical work. | Are admission control and priority rules defined for overload conditions? |