@ai-agent-lead/skills 1.0.0

package/skills/verify-real-deps/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: verify-real-deps
+description: Pre-tag smoke test against real third-party APIs. Use after `prod-ready` is clean, before tagging vN.0 — the gate that catches wire-shape mismatches that fakes accept but real upstreams reject. Triggered when the user mentions "smoke test", "real API", "live verify", "before tag", or "end-to-end against actual <vendor>". Pairs with `prod-ready` (which catches ops/infra issues tests miss) and `tdd-rounds` (the orchestration that feeds into this gate).
+complexity: high
+expected_duration: 45 minutes
+---
+
+# Verify Against Real Dependencies
+
+Tests verify the contract you wrote into the fake server. The fake accepts what you told it to accept. **Real third-party APIs enforce the contract Google / Stripe / OpenAI / etc. actually ship — and that contract drifts from any reverse-engineered model.**
+
+This skill is the explicit step between "all tests green" and "tag the release". It catches the class of bug where the fake said yes but production says no.
+
+## Why this skill exists
+
+A fake server is a *hypothesis* about the contract; the real upstream **is** the contract. Until you run code against the real upstream at least once, every test that uses the fake is testing your hypothesis. **`verify-real-deps` is the discipline that finds wire-shape bugs before users do.**
+
+See [MOTIVATION.md](./MOTIVATION.md) for a worked example showing eight such bugs surfaced after a v1.0 shipped 100% green.
+
+## When to use
+
+- After `tdd-rounds` is complete (every AC ticked).
+- After `prod-ready` checklist is filled and clean.
+- Before `git tag vN.0` and before any public announcement.
+- Any time you wonder "have we actually run this against the real upstream?" — the answer should never be "no" for a v1.0.
+
+## When to skip
+
+- The system has no third-party API integration. Pure-internal services with database-only state — `prod-ready` is enough.
+- The "real API" is your own service in a staging environment that you fully control. No reverse-engineered contract to verify.
+- A fix-round that doesn't touch the upstream-talking code path.
+
+## Workflow
+
+### 1. Set up a real-credential test environment
+
+Use real credentials in a sandbox-equivalent context (a dev project, a low-quota account, a test API key). Document what you used so a future contributor can repeat the verification.
+
+```
+Real credentials used: <handle / sandbox project / dev API key>
+Source-of-truth API host: <e.g., cloudcode-pa.googleapis.com>
+Expected limits: <so unexpected throttling stands out>
+```
+
+### 2. Run a representative end-to-end flow
+
+Pick the smallest set of operations that exercise every wire-level interaction. For an API proxy, that means at least:
+
+- Authenticate / load tier metadata.
+- Read state (quota, account info).
+- Write state if any (credential rotation, OAuth refresh).
+- The hot-path operation (the one users will hit most).
+- An error path that exercises your error-handling (a forced 429, a malformed input, a permission failure).
+
+Capture the **raw upstream response** for each — headers and body. Don't paraphrase. The body shapes are the contract.
+
+### 3. Capture every surfaced surprise
+
+Anything that worked-in-tests but doesn't-work-now is a bug. For each, write an entry in `docs/known-issues.md` (create the file lazily on first use — copy the format from [`templates/known-issues.md`](templates/known-issues.md)). The fields:
+
+- **Severity** (high / medium / low — based on user impact, not difficulty).
+- **Status** (Open / Closed in R<N> with commit hash).
+- **Reproduction** (numbered steps a stranger could follow).
+- **Root cause** (one paragraph explaining why the test passed but real didn't).
+- **Files** (which packages own the fix).
+- **Fix sketch** (one paragraph; specific enough to scope a Builder brief).
+
+The bug ledger doubles as the **canonical brief** for the fix-rounds — each entry is the Round N+M brief once the parent dispatches a fix-Builder.
+
+### 4. Iterate fix-rounds
+
+For each issue, dispatch a fix-Builder per `tdd-rounds`. Brief them with the issue's entry in the ledger. They:
+
+1. Read the issue.
+2. Reproduce.
+3. Write a failing test (often unit-test the parser / handler that mishandled the real shape).
+4. Fix.
+5. Update the upstreamtest fake / mock to match the real shape — this prevents regression in the test layer.
+6. Mark the issue **Closed** in `known-issues.md` with the commit hash and test names.
+
+After each fix-round, **re-run the same end-to-end flow** to confirm the fix works AND no other regression appeared. Issues compound — a wire-shape fix sometimes reveals a cooldown / retry / cache bug behind it.
+
+### 5. Defer or close
+
+Either the bug is fixed, or it's explicitly deferred to vN.1 with a recorded reason. No silent deferrals. If a bug is "intermittent / can't reproduce / probably the vendor", document it that way — the next contributor benefits from knowing the failure mode existed.
+
+### 6. Update the bug-prevention layer
+
+Every bug found here is also a test that should have existed. After fixing, ask: **"What test would have caught this if it had existed?"** Then add it. The fake harness should accept the **same shapes the real API does** — if the fake was too permissive, tighten it.
+
+### 7. Tag
+
+Only tag when the bug ledger has zero `Open` entries (or all `Open` entries are explicitly deferred-by-design with a tracking line in the feature doc's Non-Goals). Then:
+
+```bash
+git tag vN.0
+git push --tags
+```
+
+## Rules
+
+- **Use real credentials, not mocked ones.** The whole point is to find what the mock didn't.
+- **Don't fix issues silently.** Every bug gets a ledger entry, even one-liners. The discipline IS the value.
+- **Fix the fake too.** When you patch a wire-shape, the fake must also reject the wrong shape — otherwise the tests will accept regression.
+- **Don't extend scope.** This is a verification phase, not a feature phase. If you find a "while I'm here, let me also..." impulse, write it as a `vN.1` note and resist.
+- **Don't skip the ledger entry for "small" bugs.** A one-line fix still gets a ledger entry. The ledger is the post-mortem record.
+
+## Templates
+
+- [`templates/known-issues.md`](templates/known-issues.md) — the bug-ledger format.
+
+## Handoff
+
+When the bug ledger is clean and the same end-to-end flow runs without surprise:
+
+- Append a verification entry to `docs/STATE.md`: `## End-to-end smoke test (DONE YYYY-MM-DD)` with what was run and what was found.
+- Tag the release.
+- The bug ledger stays in `docs/known-issues.md` as a permanent post-mortem record. Future contributors read it to understand "what surprises lurk in this codebase that the test suite doesn't show."

package/skills/verify-real-deps/templates/known-issues.md

@@ -0,0 +1,45 @@
+# Known issues — post-vN.0 smoke test findings
+
+**Discovered:** YYYY-MM-DD (first end-to-end run against real <upstream>).
+**Status:** <N> open / <M> closed.
+
+These bugs slipped past unit/integration tests because the test harness accepted whatever wire shape the code sent. Real upstream enforces stricter contracts and surfaced them. Each entry doubles as the canonical brief for its fix-round.
+
+---
+
+## #N — <one-line title>
+
+**Severity:** High | Medium | Low — <one-line reason based on user impact>.
+**Status:** Open | Closed in R<N> (commit <hash>). Tests:
+`TestNameOne`,
+`TestNameTwo`.
+
+**Reproduction:**
+1. <numbered step a stranger could follow>
+2. <step>
+3. <expected vs observed>
+
+**Root cause:** <one paragraph — why the test passed but the real API didn't. Cite the test harness's permissive behavior, the real API's documented or observed contract, and the gap between them.>
+
+**Files:**
+- `<package>/<file>.go` (the function that mishandled the shape)
+- `<test-harness>/<fake>.go` (the fake that accepted the wrong shape — fix this too to prevent regression)
+
+**Fix sketch:**
+<one paragraph specific enough to scope a Builder brief. Mention the precise wire shape change, the function signature change if any, and the new test that pins the real-API contract.>
+
+---
+
+(repeat per issue)
+
+---
+
+## Fix plan
+
+**R<N> round (DONE YYYY-MM-DD):** issues #X-#Y closed in <K> dedicated commits + a simplify pass.
+**R<N+1> round (PENDING):** issue #Z.
+
+After all open issues are closed:
+- Append an end-to-end verification entry to `docs/STATE.md`.
+- Tag vN.0.
+- Leave this file in place as a permanent post-mortem record.

package/skills/zoom-out/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: zoom-out
+description: User-invoked utility — pulls the agent up an abstraction layer when the user is lost in unfamiliar code. Produces a map of relevant modules, callers, and seams in `docs/CONTEXT.md` vocabulary. Use when the user says "I'm lost", "zoom out", "give me higher-level context", "I don't know this area", "what depends on what here", or invokes the slash command. Does not change which workflow the user is in — interrupts to orient, then hands back. Skip when the user already has the map and just needs to read code.
+disable-model-invocation: true
+complexity: low
+expected_duration: 5 minutes
+---
+
+# Zoom Out
+
+A user-invoked interrupt: the user is mid-task in an unfamiliar area and needs the topology before they keep going. The skill produces a map — what modules exist, which depend on which, what the seams look like, what each is responsible for — so the user can resume their original workflow with context.
+
+This skill **does not change the workflow** the user is in. It runs once, produces the map, and hands back. The user is still in their bug-fix / feature / refactor.
+
+## When to use
+
+- User says "I'm lost", "zoom out", "give me higher-level context", "what depends on what here", "I don't know this area".
+- User invokes the slash command (`/zoom-out`).
+- A related skill (`debug`, `improve-codebase-architecture`, Workflow 4 / 5b) suggests zooming out before continuing.
+
+## When to skip
+
+- User already has the map and just needs to read code.
+- Single-file scope — there's nothing to zoom out from.
+- User is asking for a code review or a specific implementation question; zoom-out is *prelude*, not the answer.
+
+## Process
+
+### 1. Identify the area
+
+Ask the user (or infer from context) what they're trying to do. The map is scoped to *the area relevant to that task*, not the whole codebase.
+
+### 2. Read the project's vocabulary first
+
+- [`docs/CONTEXT.md`](../../docs/CONTEXT.md) — the domain glossary. Module names should come from here.
+- [`docs/architecture.md`](../../docs/architecture.md) — the system map, if it exists.
+- Any ADRs in [`docs/adr/`](../../docs/adr/) that constrain the area.
+
+If `CONTEXT.md` doesn't exist yet (greenfield repo), name modules by their file paths and flag the missing glossary as a gap.
+
+### 3. Walk the dependency graph for the area
+
+Use the Agent tool with `subagent_type=Explore` if the area is broad. Capture:
+
+- **Modules involved** — which directories / packages / files implement the responsibility.
+- **Callers** — what calls into this area, from where.
+- **Callees** — what this area calls into.
+- **Seams** — function calls, queue events, HTTP boundaries, DB tables shared across the area.
+
+### 4. Produce the map
+
+A short artifact, in chat (not on disk unless the user asks). Use the format below — it's what callers expect.
+
+```md
+## Map: <area>
+
+**Responsibility**: <one sentence — what this area does>
+
+**Modules**:
+- `<path>` — <one-line responsibility, in CONTEXT.md vocabulary>
+- ...
+
+**Callers** (who depends on this):
+- `<path>` — <how it uses the area>
+- ...
+
+**Callees** (what this depends on):
+- `<path>` — <what it provides>
+- ...
+
+**Seams**:
+- <Module A> ↔ <Module B>: <in-process | queue | HTTP | DB-shared>; <where the adapter lives>
+- ...
+
+**Decisions worth knowing**:
+- ADR-NNN: <one line — why this constraint matters here>
+- ...
+
+**Gaps spotted while mapping** (optional):
+- <e.g. "shallow module at <path> — possibly worth deepening; not blocking your task">
+```
+
+Keep it on one screen. If it doesn't fit, you over-zoomed — narrow the area.
+
+## Anti-patterns
+
+- **Drawing the whole codebase.** The map is scoped to the user's task. A full codebase tour wastes the user's attention.
+- **Listing files without responsibilities.** A list of paths isn't a map. Each entry needs a one-line "what it does", in domain vocabulary.
+- **Inventing names.** If `CONTEXT.md` calls it "Order intake", don't call it "OrderHandler" or "the order service". Use the canonical name.
+- **Persisting the map without being asked.** This skill outputs to chat. If the user wants a durable artifact, that's `system-design` (greenfield) or `improve-codebase-architecture` (brownfield) — different skills with different outputs.
+- **Making decisions during zoom-out.** This is a mapping skill, not a decision skill. Surface gaps; don't propose solutions.
+
+## Pairing with other skills
+
+- **`debug`** — runs before debug when the area is unfamiliar. Easier to bisect when you know the topology. ([`debug/SKILL.md`](../debug/SKILL.md) calls this out.)
+- **`improve-codebase-architecture`** — runs before. Map first, then propose deepening candidates.
+- **`feature-doc`** — runs before, when a feature touches an unfamiliar area and the writer needs vocabulary before drafting ACs.
+- **Any workflow** can pause for `zoom-out` and resume — the skill does not change which workflow the user is in.
+
+## Done when
+
+- The user has a one-screen map of the area, in `CONTEXT.md` vocabulary.
+- Modules, callers, callees, seams, and load-bearing ADRs are named with cite-able paths.
+- The user explicitly resumes the original task or asks a specific follow-up — don't keep mapping past their patience.