@ghostbyte/agent-docs-kit 0.0.0-stage → 4.0.2

package/skills/manage-project-quality/references/engineering-03-rate-limiting-algorithms.md

@@ -0,0 +1,48 @@
+# 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.
+
+**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
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 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? |

package/skills/manage-project-quality/references/engineering-04-production-debugging.md

@@ -0,0 +1,48 @@
+# Production Debugging
+
+# 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
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 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? |

package/skills/manage-project-quality/references/engineering-05-code-review-practices.md

@@ -0,0 +1,48 @@
+# 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
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 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? |

package/skills/manage-project-quality/references/engineering-06-data-modeling.md

@@ -0,0 +1,48 @@
+# Data Modeling
+
+# 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
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 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)? |

package/skills/manage-project-quality/references/engineering-07-cloud-cost-saving.md

@@ -0,0 +1,48 @@
+# Cloud Cost Saving
+
+# 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
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 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? |

package/skills/manage-project-quality/references/engineering-08-testing-types.md

@@ -0,0 +1,48 @@
+# Testing Types
+
+# 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
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 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? |

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

@@ -0,0 +1,48 @@
+# Message Queues
+
+# 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
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 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? |

package/skills/manage-project-quality/references/engineering-full-reference.md

@@ -0,0 +1,144 @@
+# Engineering Reference
+
+A companion to `../security-gate/SECURITY_CHECKLIST.md`. That file is pass/fail **security
+tests**; this file is **"what should I know"** — quick-recall concept lists
+for performance, infra, and engineering practice. Nothing here has a
+severity rating or a test step; use it for onboarding, self-study, or as
+context for an agent before it reviews related code.
+
+## Table of contents
+
+- [A. Speeding Up a Slow Query](#a-speeding-up-a-slow-query)
+- [B. Networking Concepts Every Dev Should Know](#b-networking-concepts-every-dev-should-know)
+- [C. Rate Limiting Algorithms](#c-rate-limiting-algorithms)
+- [D. Debugging Production Issues](#d-debugging-production-issues)
+- [E. Code Review Practices](#e-code-review-practices)
+- [F. Data Modeling Concepts](#f-data-modeling-concepts)
+- [G. Cloud Cost-Saving Techniques](#g-cloud-cost-saving-techniques)
+- [H. Types of Testing](#h-types-of-testing)
+- [I. Message Queue Concepts](#i-message-queue-concepts)
+
+> **Note:** the original "Web security vulnerabilities" list is not
+> duplicated here — it's already covered item-for-item in
+> `../security-gate/SECURITY_CHECKLIST.md` → `02_Web_Vulnerabilities`. Rate limiting
+> algorithms (below) are a companion to, not a replacement for,
+> `01_API_Security/01_rate_limiting.md`.
+
+---
+
+## A. Speeding Up a Slow Query
+
+1. Start with the explain plan
+2. Add the missing index
+3. Stop selecting *
+4. Fix N+1 queries
+5. Use a covering index
+6. Cache repeated queries
+7. Prune partitions
+8. Denormalize for reads
+9. Batch your writes
+10. Update table statistics
+
+## B. Networking Concepts Every Dev Should Know
+
+1. DNS resolution
+2. TCP handshake
+3. TLS handshake
+4. NAT
+5. Load balancer types
+6. CDN edge caching
+7. Packet loss & retransmit
+8. MTU / fragmentation
+9. Keep-alive
+10. BGP routing
+
+## C. Rate Limiting Algorithms
+
+1. Fixed window
+2. Sliding window log
+3. Sliding window counter
+4. Token bucket
+5. Leaky bucket
+6. Distributed rate limiting
+7. Client-side throttling
+8. Adaptive rate limiting
+9. Concurrency limiting
+10. Back pressure
+
+## D. Debugging Production Issues
+
+1. Correlation IDs
+2. Distributed tracing
+3. Feature flag rollback
+4. Canary analysis
+5. Replay traffic
+6. Heap dumps
+7. Chaos testing
+8. Synthetic monitoring
+9. Error budgets
+10. Postmortems
+
+## E. Code Review Practices
+
+1. Small PRs
+2. Clear description
+3. Constructive feedback
+4. Nitpick vs. blocker
+5. Fast turnaround
+6. Automated checks first
+7. Context before code
+8. Approve vs. request changes
+9. Self-review first
+10. Learning from reviews
+
+## F. Data Modeling Concepts
+
+1. Primary vs. foreign keys
+2. One-to-many
+3. Many-to-many
+4. Composite keys
+5. Soft deletes
+6. Polymorphic associations
+7. Enum vs. lookup table
+8. Audit columns
+9. Schema migrations
+10. Precision & data types
+
+## G. Cloud Cost-Saving Techniques
+
+1. Spot instances
+2. Autoscaling
+3. Reserved capacity
+4. Right-sizing
+5. Storage tiering
+6. CDN offloading
+7. Serverless for spiky loads
+8. Idle resource cleanup
+9. Compression
+10. Multi-region arbitrage
+
+## H. Types of Testing
+
+1. Unit test
+2. Integration test
+3. End-to-end test
+4. Snapshot test
+5. Contract test
+6. Load test
+7. Chaos test
+8. Mutation test
+9. Smoke test
+10. Regression test
+
+## I. Message Queue Concepts
+
+1. Producer / consumer
+2. Topic + partition
+3. Consumer group
+4. At-least-once delivery
+5. Dead letter queue
+6. Backpressure
+7. Fan-out
+8. Message ordering
+9. Idempotent consumer
+10. Offset commit

package/skills/manage-project-quality/references/engineering-protocol.md

@@ -0,0 +1,23 @@
+# Engineering review protocol
+
+## Purpose
+
+Engineering reviews improve maintainability, reliability, performance, testability, operability, and cost efficiency. They guide design and practice; they are not automatically release gates.
+
+## Statuses
+
+- `Applied`: the practice is implemented and supported by evidence.
+- `Partial`: useful parts exist, but a material gap remains.
+- `Recommended`: the practice would provide value and is not currently applied.
+- `Unverified`: available evidence cannot establish the state.
+- `N/A`: the practice does not apply; record why.
+
+If the review discovers a security vulnerability, data-loss risk, or correctness defect, report that separately rather than disguising it as an advisory recommendation.
+
+## Review approach
+
+1. Identify the system constraint or decision under review.
+2. Inspect representative code, configuration, tests, telemetry, and design records.
+3. Evaluate tradeoffs in the project’s actual scale and failure model.
+4. Prefer measurable recommendations with a verification method.
+5. Avoid importing enterprise complexity into a project that does not need it.

package/skills/manage-project-quality/references/evidence-and-reporting.md

@@ -0,0 +1,19 @@
+# Evidence and reporting
+
+## Evidence hierarchy
+
+Prefer direct evidence: relevant code lines, configuration, tests, reproducible command output, build artifacts, and authorized platform settings. Label deductions as inference and state what would confirm them.
+
+Each finding should contain:
+
+- control or practice reviewed;
+- status and severity or priority;
+- precise evidence location;
+- impact in this project;
+- remediation and responsible owner;
+- verification step;
+- limitations or assumptions.
+
+Do not paste credentials or sensitive payloads. Quote only the minimum code needed to support the finding. If line numbers are unstable, include a symbol, key, or command that allows rediscovery.
+
+In learning mode, add a short “why this matters” explanation and one concrete example. Do not require the user to repeat answers back as a condition for completing the review.

package/skills/manage-project-quality/references/security-01-design-architecture.md

@@ -0,0 +1,39 @@
+# Design & Architecture
+
+# Phase 1: Design & Architecture (Pre-Code)
+
+**When to run this:** Before writing code — during system/feature design, RFCs, or architecture review.
+
+**Goal of this pass:** Catch design-level flaws (missing trust boundaries, over-broad data collection, no threat model) that are cheap to fix now and expensive to fix after code exists.
+
+## Files in this folder
+
+| File | Purpose |
+|---|---|
+| `CHECKLIST.md` | What to check — the reference list of items, severity, and example test steps for this phase. Doesn't get filled in; copy it or use `RESULTS_TEMPLATE.md` to record a real pass. |
+| `RESULTS_TEMPLATE.md` | Fillable version of the same checklist, with Result/Notes columns and a sign-off block. Copy this file per test pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
+
+Full background, "why it matters," and references for every item live in
+`../../SECURITY_CHECKLIST.md` (search for the source file path shown in the
+checklist below).
+
+## Sign-off criteria
+
+- All Critical/High severity items must Pass or have an approved exception
+  before this phase is considered complete.
+- Total items in this phase: 5
+
+---
+
+# What to Check — Phase 1: Design & Architecture (Pre-Code)
+
+Reference checklist only — no result columns. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a test pass.
+
+| # | Source file | Item | Severity | Example test |
+|---|---|---|---|---|
+| 1 | `15_Architecture_Compliance/01_privacy_by_design.md` | Privacy by Design | Medium | Review the most recent feature's design doc and confirm data collection was scoped to only what the feature actually needs. |
+| 2 | `15_Architecture_Compliance/02_threat_modeling.md` | Threat Modeling | High | Pull the data-flow diagram for the highest-risk service and confirm a STRIDE (or equivalent) pass was actually performed and mitigations tracked to closure. |
+| 3 | `15_Architecture_Compliance/04_defense_in_depth.md` | Defense in Depth | Medium | Pick one critical asset and map every independent control protecting it; confirm there isn't a single point whose failure alone exposes it. |
+| 4 | `15_Architecture_Compliance/06_zero_trust_network.md` | Zero Trust Network Architecture | High | From inside the internal network, attempt to reach a service without presenting valid per-request authentication and confirm it's still denied. |
+| 5 | `15_Architecture_Compliance/08_secure_sdlc.md` | Secure SDLC (added) | Medium | Confirm the most recent feature had security requirements defined at design time, not bolted on after code review. |

package/skills/manage-project-quality/references/security-02-local-development.md

@@ -0,0 +1,41 @@
+# Local Development
+
+# Phase 2: Local Development
+
+**When to run this:** During day-to-day coding, before opening a pull request.
+
+**Goal of this pass:** Prevent secrets, unpinned/unvetted dependencies, and known-bad coding patterns from ever reaching a shared branch.
+
+## Files in this folder
+
+| File | Purpose |
+|---|---|
+| `CHECKLIST.md` | What to check — the reference list of items, severity, and example test steps for this phase. Doesn't get filled in; copy it or use `RESULTS_TEMPLATE.md` to record a real pass. |
+| `RESULTS_TEMPLATE.md` | Fillable version of the same checklist, with Result/Notes columns and a sign-off block. Copy this file per test pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
+
+Full background, "why it matters," and references for every item live in
+`../../SECURITY_CHECKLIST.md` (search for the source file path shown in the
+checklist below).
+
+## Sign-off criteria
+
+- All Critical/High severity items must Pass or have an approved exception
+  before this phase is considered complete.
+- Total items in this phase: 7
+
+---
+
+# What to Check — Phase 2: Local Development
+
+Reference checklist only — no result columns. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a test pass.
+
+| # | Source file | Item | Severity | Example test |
+|---|---|---|---|---|
+| 1 | `08_Release_Engineering_Version_Control/01_secure_coding_guidelines.md` | Secure Coding Guidelines | Low | Confirm the team's secure-coding cheat sheet is linked from the PR template/onboarding docs, not just filed away unused. |
+| 2 | `08_Release_Engineering_Version_Control/02_semantic_versioning.md` | Semantic Versioning | Low | Check the last 3 releases and confirm any breaking change actually bumped the MAJOR version. |
+| 3 | `10_Dependency_Supply_Chain/01_backend_dependency_scanning.md` | Dependency & SCA Scanning | High | Run the SCA scanner manually against the current backend dependency tree and confirm it matches what CI reports, with no critical CVEs unpatched past SLA. |
+| 4 | `10_Dependency_Supply_Chain/02_dependency_version_pinning.md` | Dependency Version Pinning | Medium | Delete the lockfile locally and reinstall; confirm CI fails the build if the regenerated lockfile differs from the committed one. |
+| 5 | `10_Dependency_Supply_Chain/03_frontend_dependency_scanning.md` | Frontend Dependency Scanning | Medium | Run npm audit / yarn audit and manually review any newly added package for typosquatting risk or suspicious post-install scripts. |
+| 6 | `06_Data_Protection_Secrets/06_secrets_management.md` | Secrets Management (added) | Critical | Run a secret-scanning tool (e.g. gitleaks/truffleHog) across the full git history, not just HEAD, and confirm zero committed credentials. |
+| 7 | `09_Release_Pipeline_Stages/01_local_dev_testing.md` | Stage 1: Local / Developer Testing | Low | Confirm a fresh local dev environment setup never requires copying real production credentials or data. |