fdeops 3.13.0 → 3.15.0

package/skills/fde/archive/sdlc/debug.md

@@ -1,55 +0,0 @@
-# debug - systematic, never guessing
-
-**Enter when:** something is broken, can't be reproduced, or "shouldn't be happening" - and production is NOT down (that's `rescue.md`).
-
-**Read first:** `context.md`, `terrain.md`, `chaos-log.md` (if this happened before, the cause is probably the same). Nothing else - noise kills focus.
-
-Debugging on an engagement differs from debugging your own code: no full context, no history, high pressure to "just fix it." That pressure causes the second incident. The sequence below is the protection.
-
-## Method (you do this work - never skip a step)
-
-**1. Reproduce.** Get a consistent repro before looking at any code. Can't reproduce → instrument first (logging, narrowing) - not fixes. An unreproducible bug that gets "fixed" comes back.
-
-**2. Isolate to the smallest failing case.** Strip everything that isn't the failure. Payment flow bug → does one hard-coded test transaction fail? Smallest case = smallest context = smallest blast radius for the fix.
-
-**3. Ask "what changed?" before reading code.** Last 2 hours, 24 hours, last deploy - this one question solves most production bugs:
-```bash
-git log --since="48 hours ago" --format="%ad %an %s" --date=relative
-git log --stat -5 --format="%h %s"   # works on any history depth
-```
-Don't read the codebase like a book. Write a script that answers one specific question - one execution, one answer.
-
-**4. One hypothesis.** Not three. State it explicitly:
-> "Hypothesis: X. If right, changing Y fixes it. If wrong, the symptom persists."
-A hypothesis that can't be falsified isn't one.
-
-**5. Fix the root cause, not the symptom.** A 500 is a symptom; an NPE is a symptom; the cause is upstream. Patch the symptom and you're back in a week.
-
-**6. Verify the fix holds.** Repro case passes; tests covering the changed code + downstream callers green; no new errors in logs for N minutes. Define done *before* declaring it - "seems fixed" requires another cycle.
-
-## Talking to the customer mid-debug (you coach)
-
-They'll ask for status before there is one. The FDE gives: what's narrowed, what's ruled out, what's being tested next, and **a specific time** they'll hear back. Proactive update if past that time - never make them chase. Skip the phrases that add heat: "weird one," "never seen this," "might be…". Partial clarity beats raw uncertainty. Fixed without root cause → stabilise honestly, don't close the story until the why is explainable.
-
-## Artifact
-
-**`chaos-log.md`** - append, same day:
-```markdown
-## <date> - <symptom>
-**Root cause:** <not the symptom>
-**What changed to fix it:** <change>
-**Hypotheses tested:** <in order, results>
-**Recurrence risk:** <where this can happen again>
-```
-Update `terrain.md` if the investigation disproved something the map claimed.
-
-## Checkpoint
-
-Before closing: repro passes, root cause stated in one sentence, chaos log written. If the root cause is still unknown, the incident stays open - say so.
-
-## Principles
-
-- Reproduce before touching anything. Always.
-- "What changed?" is the first question, not the last.
-- One hypothesis at a time. Three fixes failed = wrong mental model - stop.
-- Fix upstream. Symptoms patched are incidents scheduled.

package/skills/fde/archive/sdlc/observability.md

@@ -1,103 +0,0 @@
-# observability - if you can't see it running, you can't operate it
-
-**Enter when:** shipping a feature to production, the customer says "we don't know when things break," a post-incident review revealed gaps in monitoring, or the handoff needs the team to operate what was built.
-
-**Read first:** `terrain.md`, `delivery.md`, `context.md`. Load `trust-profile.md` if the data flowing through logs contains sensitive information.
-
-Code without observability is code you can't operate. The FDE who ships a feature without telemetry creates a callback in six weeks when it breaks and nobody can tell why. Observability is built alongside the feature, not after - the same way tests are.
-
-## Method (you do this work)
-
-**1. Define "working" before instrumenting.** Write 2–4 questions that the person on call will ask about this feature:
-
-```
-FEATURE: payment retry logic
-QUESTIONS ON-CALL WILL ASK:
-1. What fraction of payments succeed on first attempt vs after retry?
-2. When a payment fails permanently, why? (provider error? timeout? validation?)
-3. Is the payment provider slower than usual?
-4. Are retries causing duplicate charges?
-→ Every signal below must help answer one of these.
-```
-
-If you can't name the questions, you're not ready to instrument - you'll log everything and learn nothing.
-
-**2. Pick the right signal for each question:**
-
-| Signal | Answers | When to use |
-|--------|---------|-------------|
-| **Structured log** | "What happened in this specific case?" | Individual request debugging, audit trails |
-| **Metric** | "How often / how fast, in aggregate?" | Dashboards, alerting, trend detection |
-| **Trace** | "Where did time go across services?" | Cross-service latency, bottleneck identification |
-
-Rule of thumb: metrics tell you **that** something is wrong, traces tell you **where**, logs tell you **why**.
-
-**3. Structured logging - events, not prose.**
-
-```
-BAD:  logger.info(`Payment ${id} failed for user ${userId} after ${n} retries`)
-      → Unqueryable, inconsistent format, buried in noise
-
-GOOD: logger.info({ event: "payment_failed", payment_id: id, user_id: userId,
-        retry_count: n, error_code: "PROVIDER_TIMEOUT", duration_ms: elapsed })
-      → Queryable, alertable, structured for dashboards
-```
-
-Every log line: a stable event name + machine-readable fields. Human-readable messages are for debugging sessions; structured events are for production operations.
-
-**4. The four metrics every FDE feature needs:**
-
-| Metric | What it measures | Alert threshold |
-|--------|-----------------|-----------------|
-| **Error rate** | Failures / total requests | >2x baseline for 5 minutes |
-| **Latency (p95/p99)** | How long the operation takes | >2x normal for 5 minutes |
-| **Throughput** | Requests per second/minute | <50% of normal for 10 minutes (demand drop = upstream problem) |
-| **Business metric** | The thing the feature is supposed to improve | Direction reverses for 1 hour |
-
-The business metric is the one most FDEs skip and the one the sponsor cares about most. "Error rate is fine" means nothing if payments processed per hour dropped.
-
-**5. Alert design - avoid noise, ensure action:**
-
-| Principle | How |
-|-----------|-----|
-| **Every alert has an owner** | If nobody is named, nobody responds |
-| **Every alert has a runbook** | "Error rate spiked" → "Check these three things in this order" |
-| **Severity maps to response time** | Critical: 15 min. Warning: next business day. Info: weekly review. |
-| **No alert without action** | If the response is "ignore it" three times, delete the alert |
-
-**6. AI component observability.** AI features fail differently - they degrade, they don't crash:
-
-| What to observe | Why |
-|----------------|-----|
-| Model input/output pairs (sampled, privacy-respecting) | Detect drift: outputs changing without code changing |
-| Latency per model call | Provider degradation is gradual, not binary |
-| Fallback activation rate | If fallback fires >5%, the primary path has a problem |
-| Confidence/quality score trend | A score that slowly drops = model drift |
-| Token usage / cost per request | Cost creep is invisible until the bill arrives |
-
-**7. The sacred-data boundary.** Before shipping any observability:
-
-- Check `trust-profile.md` for `<private>` tagged data.
-- PII in logs = a breach, not a debug aid. Mask, hash, or exclude.
-- In healthcare: PHI in logs violates HIPAA. In fintech: PANs in logs violate PCI-DSS.
-- Default: log IDs, not values. `user_id: 12345` not `user_email: jane@...`
-
-## Artifact
-
-**`delivery.md`** - under each shipped feature: what's observable, where to look, alert thresholds, the runbook.
-
-**`handoff.md`** (when close approaches) - the on-call guide: "what each alert means and what to do."
-
-**`risks.md`** - if observability gaps were found in existing code: what's unobserved and the risk it carries.
-
-## Checkpoint
-
-Before marking a feature shipped: the four metrics are emitting, alerts have owners and runbooks, sacred data is not in logs. If any gap: "Observability incomplete - <specific gap> - shipping without it means <specific risk>."
-
-## Principles
-
-- Define the questions before choosing the signals. Unquestioned telemetry is noise.
-- Metrics for detection, traces for location, logs for explanation.
-- Every alert has an owner and a runbook, or it's noise.
-- AI features need observability for drift, not just failures.
-- PII in logs is a breach. Default to IDs, not values.

package/skills/fde/archive/sdlc/qa-live.md

@@ -1,113 +0,0 @@
-# qa-live - test it like a user, not like an engineer
-
-**Enter when:** a feature is built and needs to be verified from the user's perspective, the team says "it works on my machine," a demo is coming and the feature hasn't been clicked through, or a post-deploy smoke test is needed.
-
-**Read first:** `delivery.md` (what was built), `decisions.md` (acceptance criteria), `success.md` (what the customer expects to see), `context.md`.
-
-Unit tests prove the code works. QA proves the *feature* works - from the user's chair, on a real browser, with real data patterns. The FDE who ships a feature that passes all tests but fails the first user click has shipped a defect.
-
-## Method (you do this work)
-
-**1. Write the test script from the user's story, not the code.**
-
-Start with `success.md` and `decisions.md` acceptance criteria. For each acceptance criterion, write the human steps:
-
-```markdown
-## Test: User can retry a failed payment
-Precondition: User has a failed payment in their history
-Steps:
-  1. Navigate to payment history
-  2. Click the failed payment
-  3. Click "Retry payment"
-  4. Confirm the retry dialog
-  5. Observe the result
-Expected: Payment processes successfully, status updates to "Completed"
-Also check: Error message if retry fails, loading state during processing
-```
-
-**2. The five perspectives.** Test each feature from five angles that unit tests can't reach:
-
-| Perspective | What to test | Common FDE finding |
-|------------|-------------|-------------------|
-| **Happy path** | Does the main flow work end-to-end? | Works locally, fails with real data volumes |
-| **Error path** | What happens when things go wrong? | Error messages are developer-facing, not user-facing |
-| **Edge cases** | Empty states, max lengths, special characters, concurrent users | The empty state shows "undefined" instead of a helpful message |
-| **Performance** | Is it fast enough for real use? | Works fine with 10 records, unusable with 10,000 |
-| **Accessibility** | Can it be used with keyboard only? Does the screen reader make sense? | Tab order is broken, focus traps in modals |
-
-**3. Real browser testing.** Open the actual application in a browser and click through:
-
-```
-Before each test:
-  - Clear relevant caches/state
-  - Use realistic test data (not "test test test")
-  - Note the browser and viewport size
-
-During each test:
-  - Open DevTools console - watch for errors
-  - Open DevTools network tab - watch for failed requests
-  - Time the critical actions (user-perceivable latency)
-
-After each test:
-  - Screenshot the result (before/after when relevant)
-  - Note any console errors even if the test "passed"
-  - Note any UX friction even if technically correct
-```
-
-**4. The health score.** Rate the feature across five dimensions, 1–5:
-
-| Dimension | 1 (broken) | 3 (acceptable) | 5 (polished) |
-|-----------|-----------|----------------|--------------|
-| **Functionality** | Critical path fails | Happy path works, errors unhandled | All paths work, errors graceful |
-| **Performance** | >5s load time | <2s load time | <500ms load time, no layout shifts |
-| **Error handling** | Crashes or shows stack trace | Shows error message | Shows actionable error with recovery option |
-| **Data handling** | Corrupts or loses data | Handles normal data correctly | Handles edge cases (empty, large, special chars) |
-| **User experience** | Confusing or broken layout | Functional but rough | Intuitive, consistent with the rest of the app |
-
-**Overall health = average of five scores.** Below 3.0 → not ready to ship. 3.0–4.0 → shippable with known issues. 4.0+ → confident to demo.
-
-**5. The bug report format.** For each issue found:
-
-```markdown
-## Bug: <one-line summary>
-Severity: critical / high / medium / low
-Steps to reproduce:
-  1. <exact steps>
-  2. <exact steps>
-Expected: <what should happen>
-Actual: <what happened>
-Evidence: <screenshot, console error, network request>
-Environment: <browser, viewport, data state>
-```
-
-**6. Re-verify after fixes.** After each bug is fixed:
-- Re-run the exact reproduction steps
-- Check that the fix didn't break adjacent functionality
-- Update the health score
-- Screenshot the fixed state
-
-## Artifact
-
-**`delivery.md`** - the health score and test results for each shipped feature:
-```markdown
-## QA: <feature name> - <date>
-Health score: 4.2 / 5.0
-Tests run: 8 passed, 1 failed (fixed), 1 known issue (low severity)
-Bugs found: 2 (1 fixed, 1 deferred to next sprint)
-Ready to demo: YES / NO
-```
-
-**`decisions.md`** - bugs deferred with rationale (why it's acceptable to ship with this known issue).
-
-## Checkpoint
-
-One line: "Feature tested from user perspective. Health score: <N>/5. <N> bugs found, <N> fixed, <N> deferred. Ready to demo: yes/no." If not ready: the specific blocker.
-
-## Principles
-
-- Test from the user's chair, not the developer's IDE.
-- Real browser, real data patterns, real network conditions.
-- Console errors during a "passing" test are still findings.
-- Health score below 3.0 = not ready to ship, regardless of test suite.
-- Every bug gets a reproduction recipe, not a description.
-- A feature that passes all unit tests but fails the first click is a defect.

package/skills/fde/archive/sdlc/security-audit.md

@@ -1,105 +0,0 @@
-# security-audit - find the holes before someone else does
-
-**Enter when:** the engagement touches auth, payments, user data, or external integrations; the customer mentions compliance (SOC2, PCI, HIPAA); a new API endpoint is being shipped; or the FDE is asked "is this secure?"
-
-**Read first:** `trust-profile.md` (data classification, AI policy, compliance requirements), `terrain.md`, `context.md`. Load the relevant regulated overlay (fintech/healthcare/gov) if the signal is present.
-
-On an FDE engagement, security mistakes are twice as dangerous: you break someone else's system, with their users' data, under their compliance obligations. The FDE who finds the vulnerability before production earns trust that lasts the entire engagement.
-
-## Method (you do this work)
-
-**1. Threat model in five minutes.** Not a ceremony - five questions before looking at code:
-
-| Question | What it reveals |
-|----------|----------------|
-| Where does untrusted data enter? | HTTP requests, file uploads, webhooks, LLM outputs, message queues |
-| What's worth stealing? | Credentials, PII, payment data, API keys, session tokens |
-| What's worth breaking? | Auth system, payment flow, admin actions, data integrity |
-| Who's the attacker? | External (internet), internal (employee), adjacent (other tenant), automated (bot) |
-| What's the worst realistic outcome? | Data breach, financial loss, regulatory fine, reputation damage |
-
-Write the answers before scanning code. The threat model tells you where to look; code scanning without a threat model is reading every room in a building instead of checking the doors.
-
-**2. The STRIDE pass.** For each trust boundary (where data crosses from untrusted to trusted):
-
-| Threat | Check | Common FDE finding |
-|--------|-------|-------------------|
-| **Spoofing** | Can someone impersonate a user/service? | Missing auth on internal endpoints ("it's behind the VPN" is not auth) |
-| **Tampering** | Can data be altered in transit or at rest? | Unparameterised SQL, unsigned webhooks, client-side validation as sole gate |
-| **Repudiation** | Can an action be denied later? | No audit log on admin actions, no timestamp on state changes |
-| **Information disclosure** | Can data leak? | Stack traces in production errors, PII in logs, verbose error messages |
-| **Denial of service** | Can it be overwhelmed? | No rate limiting on auth endpoints, unbounded file uploads, no pagination |
-| **Elevation of privilege** | Can a user gain access they shouldn't? | IDOR (changing user ID in URL), missing role checks on endpoints |
-
-**3. The automated scan.** Run these - they catch what manual review misses:
-
-```bash
-# Secrets in code (repeat --include per extension)
-grep -rnE "(api[_-]?key|secret|password|token|private[_-]?key)\s*[:=]\s*['\"][^'\"]{8,}" \
-  --include="*.js" --include="*.ts" --include="*.py" --include="*.env" \
-  --include="*.yaml" --include="*.json" . | grep -vE "example|template|test|mock" | head -20
-
-# Dependency vulnerabilities
-npm audit 2>/dev/null || pip audit 2>/dev/null || echo "no package audit available"
-
-# SQL injection patterns
-grep -rnE "(SELECT|INSERT|UPDATE|DELETE).*\+.*\"|f['\"].*{.*}.*SELECT" \
-  --include="*.js" --include="*.ts" --include="*.py" . | head -10
-
-# Dangerous patterns
-grep -rnE "eval\(|innerHTML\s*=|document\.write\(|exec\(|__import__" \
-  --include="*.js" --include="*.ts" --include="*.py" . | head -10
-```
-
-**4. The AI security check.** If the system uses AI/LLM components:
-
-| Check | Finding if yes |
-|-------|---------------|
-| Is model output used in SQL, shell commands, or HTML without sanitisation? | Injection via prompt - treat model output as untrusted input |
-| Is the system prompt relied on as a security boundary? | Prompt injection bypasses it - enforce permissions in code |
-| Are secrets or cross-tenant data in the context window? | Data leakage via prompt extraction |
-| Are tool/agent permissions scoped? | Excessive agency - model can take actions it shouldn't |
-| Are token/rate/recursion limits set? | Unbounded consumption or infinite loops |
-
-**5. Classify findings by severity and action:**
-
-| Severity | Criteria | Action |
-|----------|----------|--------|
-| **Critical** | Exploitable now, real data at risk | Stop other work. Fix before next merge. |
-| **High** | Exploitable with effort, or compliance violation | Fix this phase. Track in `risks.md`. |
-| **Medium** | Defense-in-depth gap, no immediate exploit | Log it. Fix when the module is next touched. |
-| **Low** | Best practice gap, no exploit path | Note for the handoff document. |
-
-**6. Present findings as protection, not criticism.**
-
-The internal team built this system under constraints. Frame findings as shared wins:
-
-> "Found three endpoints without rate limiting - adding that now prevents the bot attack that hit [company in their industry] last quarter. Here's the fix."
-
-Not: "Your auth is broken." Even if it is.
-
-## Artifact
-
-**`risks.md`** - each finding with severity, evidence, remediation, and status:
-```markdown
-## Security finding: <title> - <severity>
-Where: <file:line or endpoint>
-Evidence: <what you found>
-Risk: <what an attacker could do>
-Remediation: <specific fix>
-Status: fixed / in-progress / logged-for-handoff
-```
-
-**`trust-profile.md`** - update if new sensitive data paths, AI components, or compliance requirements were discovered.
-
-## Checkpoint
-
-Summary to the FDE: findings by severity count, the one critical/high finding that needs immediate attention (if any), and the overall security posture in one sentence. If no critical findings: "No exploitable issues found in this pass - next audit at <trigger>."
-
-## Principles
-
-- Threat model first, scan second. Know where to look before looking everywhere.
-- Treat model output as untrusted input - always.
-- Frame findings as protection, not criticism. The team built under constraints.
-- Secrets in code outrank every other finding. Check first.
-- A security audit with no findings either found nothing or didn't look hard enough - state which.

package/skills/fde/archive/sdlc/test-on-legacy.md

@@ -1,108 +0,0 @@
-# test-on-legacy - making changes safe on code that has no tests
-
-**Enter when:** the codebase has little or no test coverage, you need to change code where tests are absent or misleading, or `terrain.md` flagged high-churn modules with no test neighbours.
-
-**Read first:** `terrain.md` (the churn heat map), `decisions.md` (the current slice), `context.md`. This skill is the safety net for building on someone else's untested codebase.
-
-Legacy code without tests is a minefield. You can't refactor it because you don't know what it does. You can't add features because you don't know what you'll break. The way through: characterise what exists, wrap the change, prove it works - in that order.
-
-## Method (you do this work)
-
-**1. Characterisation tests first.** Before changing anything, write tests that describe what the code *actually does right now* - including the parts that seem wrong:
-
-```
-The code truncates names at 50 characters.
-  → That seems like a bug, but it might be a contract another system depends on.
-  → Write a test: "truncates names at 50 characters" - that's the characterisation.
-  → NOW you can change the code and know exactly what you've broken.
-```
-
-Characterisation tests answer: "What does this code do?" not "What should this code do?" They're the honest documentation that the README isn't.
-
-**How to write them:**
-1. Pick the function/module you're about to change.
-2. Call it with representative inputs (from production if possible, from logs, from the team's knowledge).
-3. Record what comes back - that's your expected output.
-4. Turn that into an assertion.
-
-```
-# The pattern:
-result = function_under_test(real_input)
-assert result == whatever_it_actually_returned  # characterisation, not specification
-```
-
-**2. The Strangler Fig pattern - wrap, don't rewrite.**
-
-Never rewrite legacy code in place. Instead:
-
-```
-Step 1: New interface wraps the old code (calls through to it)
-  → All existing callers work exactly as before
-  → Your characterisation tests pass
-
-Step 2: New implementation behind the new interface
-  → Old code still there, still callable
-  → Feature flag or config switches between old and new
-
-Step 3: Gradually migrate callers to the new path
-  → Each migration is a small, testable change
-  → Old path remains as fallback
-
-Step 4: Remove old code only when:
-  → No callers remain
-  → New path has been stable for N days
-  → Team agrees it's safe
-```
-
-**3. The test pyramid for legacy engagement work:**
-
-| Level | What to write | How many | Why |
-|-------|-------------|---------|-----|
-| **Characterisation** | What the code does now | 3–5 per module you're changing | Safety net before any change |
-| **Unit** | Your new code's behaviour | 1 per new function/method | Proves your addition works |
-| **Integration** | The seam between old and new | 1–2 per boundary | Proves old and new cooperate |
-| **Smoke** | The critical user path end-to-end | 1 per feature | Proves the user can still do the thing |
-
-**4. Spot the lying tests.** Worse than no tests are tests that pass but verify nothing:
-
-```
-# This test passes and proves nothing:
-def test_process_payment():
-    result = process_payment(mock_everything())
-    assert result is not None  # what does "not None" prove?
-
-# This test is actually testing something:
-def test_process_payment_deducts_from_balance():
-    account = create_account(balance=100)
-    process_payment(account, amount=30)
-    assert account.balance == 70
-```
-
-When you find a lying test: note it in `terrain.md`. Don't fix it unless it's in your slice - but name it, because the next person needs to know.
-
-**5. The "safe to change" checklist.** Before modifying any legacy code:
-
-- [ ] Characterisation tests written for the module being changed
-- [ ] All characterisation tests pass before your change
-- [ ] Your change is wrapped (Strangler Fig), not a rewrite-in-place
-- [ ] New tests cover your new behaviour
-- [ ] All tests (characterisation + new) pass after your change
-- [ ] The diff shows only what you intended to change
-
-## Artifact
-
-**`terrain.md`** - update test-gap assessment: which modules now have characterisation tests, which still don't, which tests are lying.
-
-**`decisions.md`** - log: "Added characterisation tests for <module> before changing <feature>. Coverage state: <before/after>."
-
-## Checkpoint
-
-Before merging any change to legacy code: characterisation tests existed before the change (state which), new tests cover the new behaviour, all pass. If characterisation tests were skipped: that's a finding - state why (time pressure? inaccessible code?) and log the risk.
-
-## Principles
-
-- Characterise before changing. What the code does > what it should do.
-- Wrap, don't rewrite. The Strangler Fig is the safest pattern on legacy code.
-- A lying test is worse than no test. Name it when you find it.
-- The ugly behaviour in the characterisation test might be someone else's contract. Don't "fix" it without asking.
-- Test coverage on legacy code is insurance - buy it before you need it, not after.