@brunosps00/dev-workflow 0.8.1 → 0.10.0

package/scaffold/skills/dw-source-grounding/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: dw-source-grounding
+description: Discipline of grounding architectural and dependency decisions in versioned official documentation, with mandatory citations. Other commands invoke this skill when they need to decide based on framework/library behavior — never on hallucinated APIs or stale Stack Overflow answers. Adapted from addyosmani/agent-skills (MIT).
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - WebFetch
+---
+
+# dw-source-grounding
+
+Behavioral protocol for grounding decisions in **versioned, official documentation** — and citing those sources verifiably. Used by `dw-create-techspec`, `dw-deps-audit`, `dw-deep-research` whenever a decision depends on what a framework or library actually does at the version installed in the project.
+
+## Why this skill exists
+
+Decisions made on hallucinated APIs or 2-year-old Stack Overflow answers cause silent breakage. The cost shows up later — code that "worked in testing" because the agent matched an older version's API, then breaks in production where the real version is different. This skill enforces a four-step protocol that prevents that class of failure.
+
+## When to Use
+
+Read this skill when:
+
+- A command needs to recommend a library/framework version (`dw-deps-audit` brainstorm phase).
+- A command must propose architectural patterns that depend on framework specifics (`dw-create-techspec`).
+- A command is researching a topic that has version-specific answers (`dw-deep-research`).
+- You're about to cite an API, CLI flag, configuration option, or behavior — and you want the citation to be verifiable later.
+
+Do NOT use when:
+
+- The decision doesn't depend on external documentation (e.g., naming a variable inside a single function).
+- The library/framework version is irrelevant to the answer (e.g., "use a hash map for O(1) lookup").
+- You're writing examples that are intentionally generic / pseudocode.
+
+## The Protocol — Detect → Fetch → Implement → Cite
+
+### 1. Detect — read the actual version first
+
+Before researching anything, read the project's manifest and identify the EXACT version of the library/framework that matters:
+
+| Stack | File | Field |
+|-------|------|-------|
+| Node/TS | `package.json` | `dependencies`, `devDependencies` |
+| Python | `pyproject.toml`, `requirements*.txt`, `Pipfile.lock` | each dep with version |
+| .NET | `*.csproj`, `packages.lock.json` | `PackageReference Version="..."` |
+| Rust | `Cargo.toml`, `Cargo.lock` | `[dependencies]` |
+
+Record the version. If a range (`^4.18.0`), note the lockfile-resolved version.
+
+If no manifest exists OR the dep is not yet in the manifest (e.g., choosing what to install), record "no version yet — choosing fresh".
+
+### 2. Fetch — pull the matching version's official docs
+
+Authority hierarchy:
+
+1. **Official docs** for the EXACT version (or nearest stable). E.g., `react.dev/reference/react?version=18` not `react.dev` default.
+2. **Official changelog / migration guide** when transitioning across versions.
+3. **Web standards** (MDN, RFCs, W3C) for cross-implementation behavior.
+4. **Compatibility tables** (caniuse, Compat data) for API support across runtimes.
+
+Forbidden as primary source:
+
+- Stack Overflow answers (use only as discovery, then verify via official).
+- Tutorial blogs (frequently outdated; never authoritative).
+- AI training data (your training is months/years stale).
+- README screenshots from random GitHub repos.
+
+Fetch via `WebFetch` or `mcp__context7__*` if available. If both fail, surface to the user that you're falling back to training-data knowledge AND mark the citation `[source: training-data, unverified]`.
+
+### 3. Implement — apply the documented pattern
+
+Use exactly the API the documented version provides. Don't mix patterns from multiple versions ("this useEffect example is from React 16; you're on 18.3"). When the doc shows multiple acceptable patterns, pick the simplest that matches the project's style.
+
+If the doc presents migration warnings (e.g., "deprecated in v5, use X instead"), follow the new path unless the project explicitly pins to the old version for a documented reason.
+
+### 4. Cite — record the source verifiably
+
+Every decision that depended on an external source ends with a citation block:
+
+```
+[source: <url>, version: <X.Y>, retrieved: <YYYY-MM-DD>]
+```
+
+Examples:
+
+```
+[source: https://react.dev/reference/react/useEffect, version: 18.3, retrieved: 2026-05-07]
+[source: https://docs.python.org/3.12/library/asyncio-task.html, version: 3.12, retrieved: 2026-05-07]
+[source: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html, version: SDK v3, retrieved: 2026-05-07]
+```
+
+When citing in PRDs, techspecs, decision logs, or deps-audit reports, the citation is mandatory adjacent to each claim. A future engineer reading the doc can click and verify.
+
+## How `dw-create-techspec` uses this
+
+Before writing the "Architectural Decisions" section, the techspec command:
+
+1. Lists every framework/library decision the techspec depends on (e.g., "use Server Actions for mutations").
+2. For each, runs the protocol: detects version, fetches official doc, cites verifiably.
+3. Writes each decision as: `<decision> — <one-line rationale> — [source: ...]`.
+
+If the protocol can't reach official docs (offline, paywall, dead link), the techspec prefixes the decision with `⚠ training-data fallback` so the human reviewer knows to verify.
+
+## How `dw-deps-audit` uses this
+
+In the brainstorm phase (Conservative/Balanced/Bold per package), each option's "target version" cites the source where that version's release notes were checked. This catches the "agent recommends v5 because it sounds modern, but v5 dropped Node 18 support" class of error.
+
+## How `dw-deep-research` uses this
+
+Already does multi-source research; gains the citation discipline. Each finding line ends with a `[source: ...]` block. The output report's bibliography is built from these citations automatically.
+
+## Anti-patterns
+
+1. Citing Stack Overflow as primary source. (Use as DISCOVERY, then fetch the official doc the SO answer points to.)
+2. Citing "the docs" without a URL. The whole point is verifiability.
+3. Citing a doc URL that isn't pinned to a version (e.g., `react.dev` instead of `react.dev/reference/react?version=18`).
+4. Pretending knowledge is current when it's training data. Mark unverified.
+5. Citing your own previous answer in this session as authority. The chain has to terminate at an external source.
+
+## References
+
+- `references/citation-protocol.md` — exact format of `[source: ...]` blocks; how to consolidate multiple citations in a single decision; how to track citation freshness over time.
+- `references/source-priority.md` — full hierarchy with examples; when secondary sources are acceptable.
+- `references/freshness-check.md` — how to validate a doc URL still applies to the version in use; how to detect doc drift between when you fetched and when the user reads the artifact.
+
+## Inspired by
+
+Adapted from [`addyosmani/agent-skills/source-driven-development`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT license). Core protocol (Detect → Fetch → Implement → Cite) and source authority hierarchy preserved. dev-workflow integration: invoked by `dw-create-techspec`, `dw-deps-audit`, `dw-deep-research` via Complementary Skills, and citation format aligned with our existing report frontmatter conventions (`type: ...`, `schema_version: ...`).

package/scaffold/skills/dw-source-grounding/references/citation-protocol.md

@@ -0,0 +1,108 @@
+# Citation protocol — exact format of `[source: ...]` blocks
+
+Citations are not optional decoration. They turn a decision into a verifiable claim. Future engineers reading a techspec/deps-audit/research report click the URL and confirm.
+
+## Required format
+
+Single citation:
+
+```
+[source: <url>, version: <X.Y>, retrieved: <YYYY-MM-DD>]
+```
+
+All three fields required:
+
+- `<url>` — direct URL to the section/page that supports the claim. Not the docs homepage.
+- `<version>` — the version of the library/framework the URL applies to. If the URL is version-pinned (e.g., `?version=18`), the value here matches.
+- `<retrieved>` — ISO date you fetched. Establishes when the doc was current.
+
+Examples (good):
+
+```
+[source: https://react.dev/reference/react/useEffect, version: 18.3, retrieved: 2026-05-07]
+[source: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations, version: 14.2, retrieved: 2026-05-07]
+[source: https://docs.python.org/3.12/library/asyncio.html, version: 3.12, retrieved: 2026-05-07]
+[source: https://docs.docker.com/compose/compose-file/build/, version: Compose Spec, retrieved: 2026-05-07]
+```
+
+Examples (bad):
+
+```
+[source: react.dev]                           # no version, no date, not pinned
+[source: docs, retrieved: today]              # vague URL, vague date
+[source: https://stackoverflow.com/q/12345]   # not authoritative — see source-priority.md
+[the React docs say ...]                      # not a citation block; future reader can't verify
+```
+
+## Multiple citations on one decision
+
+When a decision rests on more than one source (e.g., "use Server Actions for mutations" depends on the React 19 form actions API + the Next.js 14 routing layer), list each:
+
+```
+Decision: use Server Actions for the form submission flow.
+
+Rationale: Server Actions provide automatic revalidation
+[source: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations, version: 14.2, retrieved: 2026-05-07]
+and align with React 19's `useActionState`
+[source: https://react.dev/reference/react/useActionState, version: 19.0, retrieved: 2026-05-07].
+```
+
+Inline form for short claims:
+
+```
+- Postgres 16 introduces `pg_stat_io` for IO observability
+  [source: https://www.postgresql.org/docs/16/monitoring-stats.html, version: 16, retrieved: 2026-05-07].
+```
+
+## Where citations live
+
+Per artifact:
+
+| Artifact | Citations live in |
+|----------|-------------------|
+| PRD (`prd.md`) | "Open Questions" section when the answer needs research, OR inline next to specific functional requirements |
+| TechSpec (`techspec.md`) | Inline next to every architectural decision; consolidated in a "Sources" section at the end |
+| Deps-audit report | Adjacent to each package's recommended version |
+| Deep-research report | Inline next to every finding; consolidated bibliography auto-generated |
+| ADR | Mandatory in the "References" section |
+
+## Freshness notation
+
+If the citation is older than 90 days when the artifact is consumed, suspect drift. Best-practice:
+
+- Re-verify the citation before acting on the decision.
+- If the cited URL has moved or been deprecated, update the artifact: `[source: <new-url>, version: ..., retrieved: <new-date>, supersedes: <old-url>]`.
+
+For artifacts that age (e.g., a 6-month-old ADR), agents reading them downstream should flag stale citations rather than silently trust them.
+
+## Unverified fallback
+
+When official docs are unreachable (network down, paywall, deleted page) AND the agent must still produce an answer, mark the citation explicitly:
+
+```
+[source: training-data, unverified, claim: <X>, last-known-version: <Y>]
+```
+
+This signals to the human reviewer that the answer needs verification before commit.
+
+NEVER use `unverified` as a default. The four-step protocol (Detect → Fetch → Implement → Cite) demands fetch attempts; `unverified` is the failsafe, not the path.
+
+## Consolidation in reports
+
+When a report has dozens of citations (e.g., a deep-research output), build a numbered bibliography at the end:
+
+```
+## Sources
+
+[1] https://react.dev/reference/react/useEffect, version: 18.3, retrieved: 2026-05-07
+[2] https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations, version: 14.2, retrieved: 2026-05-07
+[3] https://docs.python.org/3.12/library/asyncio.html, version: 3.12, retrieved: 2026-05-07
+```
+
+In-line, refer to bibliography entries: `... uses Server Actions [2] for mutations ...`.
+
+## Don't
+
+- Don't cite an internal Slack thread or private wiki as if it were authoritative — the citation must point to something the reader can read.
+- Don't cite a URL that requires login (paywalls); find an open-access equivalent or note the access barrier in the citation.
+- Don't backfill citations after the fact ("I'll add the source later"). Cite as you decide; if you can't cite, you don't have a verified decision.

package/scaffold/skills/dw-source-grounding/references/freshness-check.md

@@ -0,0 +1,108 @@
+# Freshness check — keeping citations valid over time
+
+A citation goes stale in two ways: the URL stops resolving (404, redirect, paywall added) OR the project's installed version moves past the version the citation pinned. Both invalidate the citation's authority. This file describes how to detect both and what to do.
+
+## Two staleness modes
+
+### Mode 1 — URL drift
+
+The URL still loads, but the content has changed (doc was rewritten, section deleted, deprecated). Or the URL 404s outright.
+
+Detection: re-fetch the URL on demand. Compare the section/heading the original citation pointed to.
+
+Action when detected:
+- If the new content still supports the original claim → update the citation's `retrieved` date.
+- If the new content contradicts or removes the claim → the citation is invalid. Find a replacement source OR revisit the decision.
+
+### Mode 2 — Version drift
+
+The URL is fine, but the project bumped from React 18.3 to React 19. The citation `[..., version: 18.3, ...]` no longer pins to the version installed.
+
+Detection: compare the cited version with the manifest's current version (`package.json` etc.). Mismatch → drift.
+
+Action:
+- If the doc has version-aware content (most modern docs do), find the equivalent for the new version.
+- If the API was renamed/removed in the new version, the underlying decision needs re-evaluation, not just a citation patch.
+
+## When to check freshness
+
+| Trigger | Check what |
+|---------|-----------|
+| Acting on an artifact older than 90 days | Both URL drift and version drift |
+| About to ship code based on a citation | URL drift (single fetch) |
+| User explicitly asks "is this still current?" | Both |
+| Routine `dw-deps-audit` | Version drift for every cited dep |
+
+Don't check on every read — that turns documentation into a trip hazard. Check at decision points: before committing, before merging, before promoting to production.
+
+## How to check programmatically
+
+For URL drift:
+
+```bash
+# Quick HEAD check — does the URL still resolve?
+curl -sI "<url>" | head -1
+# 200 OK → fine; 301/302 → follow; 404 → broken; 403 → paywall added
+
+# Content drift check — fetch and grep for the original heading
+curl -s "<url>" | grep -i "<expected-heading-or-section>"
+```
+
+In an agent context: use `WebFetch` on the URL and confirm the cited section still exists. If a heading the citation referenced is gone, mark the citation as drift.
+
+For version drift:
+
+```bash
+# What does the manifest say now?
+node -p "require('./package.json').dependencies.react"
+# Compare to the cited version in the artifact
+```
+
+In an agent context: read the manifest, parse the dep version, compare to the citation's `version` field.
+
+## Updating stale citations
+
+When a citation drifts but the underlying decision still holds, update in place:
+
+```
+Before:
+[source: https://react.dev/reference/react/useEffect, version: 18.3, retrieved: 2025-09-01]
+
+After URL drift detected (page restructured):
+[source: https://react.dev/reference/react/useEffect, version: 18.3, retrieved: 2026-05-07,
+ superseded-by: https://react.dev/learn/synchronizing-with-effects, retrieved: 2026-05-07]
+
+After version drift (project moved to React 19):
+[source: https://react.dev/reference/react/useEffect, version: 19.0, retrieved: 2026-05-07,
+ previous: 18.3]
+```
+
+The artifact records the history. Reviewers can see: "this decision was first sourced for v18.3 in Sep 2025; re-verified for v19.0 in May 2026."
+
+## When the underlying decision dies
+
+Sometimes drift means the API the decision used no longer exists. Example: a decision in 2023 to use `React.useTransition` with the `pending` second tuple element. In React 18.3 that's the API; in React 19 the API shape changed.
+
+In this case:
+
+1. Don't silently update the citation. The decision IS now invalid.
+2. Open an ADR or comment in the techspec: "decision X relied on API Y; API Y was changed in v<new>; need to revisit."
+3. Loop the user (or the next iteration of `dw-create-techspec`/`dw-deps-audit`) into the decision, with the new constraint.
+
+Quietly patching a stale citation when the underlying API is gone is a subtle category of bug. Surface it.
+
+## Bibliography rotation in long-lived artifacts
+
+For artifacts that live more than 6 months (long-running PRDs, ADRs, design docs), consider a "Sources last verified: YYYY-MM-DD" header at the top:
+
+```markdown
+---
+type: techspec
+schema_version: "1.0"
+sources_last_verified: 2026-05-07
+---
+```
+
+When an agent re-reads the artifact and the verification date is >90 days old, prompt: "Sources last verified <date>; re-run freshness check?"
+
+Cheap operational discipline; prevents silent decay.

package/scaffold/skills/dw-source-grounding/references/source-priority.md

@@ -0,0 +1,146 @@
+# Source priority — what counts as authoritative
+
+Not all sources are equal. The whole point of grounded development is using authoritative sources, not the loudest ones. This file is the hierarchy.
+
+## Tier 1 — Authoritative
+
+These are the only valid PRIMARY sources. Cite these for any claim about how a library, framework, or standard works.
+
+### 1.1 Official versioned documentation
+
+The exact version's published docs:
+
+- React: `react.dev/reference/react?version=<X>`
+- Next.js: `nextjs.org/docs` (versioned via release page)
+- Python: `docs.python.org/<X.Y>/`
+- Node: `nodejs.org/api/` (version-pinned via dropdown / URL `/dist/v<X.Y.Z>/`)
+- ASP.NET Core: `learn.microsoft.com/aspnet/core/` (filter by version)
+- Rust: `doc.rust-lang.org/<X.Y>/` and `docs.rs/<crate>/<version>/`
+- Postgres: `postgresql.org/docs/<major>/`
+- AWS: `docs.aws.amazon.com/<service>/` (versioned per SDK / API)
+
+When the URL doesn't pin version, add a query (`?v=`, `?version=`) or use the docs section that explicitly states the version. If neither exists, note in the citation: `version: latest-as-of-retrieved`.
+
+### 1.2 Official changelogs and migration guides
+
+For decisions involving version transitions (upgrade from v17 to v18, etc.):
+
+- React's `react.dev/blog` for major releases
+- Next.js's `nextjs.org/docs/app/building-your-application/upgrading`
+- Maintainer-published `CHANGELOG.md` in the repo root
+
+### 1.3 Web standards & RFCs
+
+For cross-implementation behavior:
+
+- W3C specs (e.g., HTML, CSS specs)
+- WHATWG specs (e.g., Fetch, URL)
+- IETF RFCs (e.g., RFC 7807 Problem Details, RFC 9110 HTTP Semantics)
+- ECMA-262 (JavaScript spec)
+- ISO standards when relevant (e.g., ISO 8601 for dates)
+
+Cite when the question is "is this behavior portable?" or "what's the standard?"
+
+### 1.4 Compatibility tables
+
+For "does X work in browser/runtime Y?":
+
+- caniuse.com for web platform features
+- MDN's Browser Compat Data (BCD) for Web APIs
+- Compatibility tables published in maintainer docs (Postgres has them, Node has them)
+
+## Tier 2 — Acceptable as supplement, NOT primary
+
+Cite Tier 2 ONLY in addition to a Tier 1 source — never as the sole basis for a decision.
+
+### 2.1 Maintainer blog posts
+
+Examples:
+
+- `vercel.com/blog/...` — for Vercel-published deep-dives on Next.js patterns
+- `microsoft.com/devblogs/...` — for ASP.NET / .NET deep-dives
+- `engineering.<company>.com` — when the company maintains the project
+
+These are first-person from people who built the thing. Often clearer than docs. But docs are the contract; blogs are commentary.
+
+### 2.2 Conference talks (recorded)
+
+Examples:
+
+- React Conf, Next.js Conf, Pycon, Rustconf
+- The talk's slides + speaker handle
+
+When citing, name the talk + year + speaker; link the video.
+
+### 2.3 GitHub issues / PRs from the maintainer
+
+Useful for understanding the WHY behind a doc statement. Cite the issue/PR number explicitly:
+
+```
+[source: https://github.com/vercel/next.js/issues/12345, retrieved: 2026-05-07]
+(maintainer thread on the rationale for App Router's caching behavior)
+```
+
+## Tier 3 — Discovery only, NEVER cite as primary
+
+These help you find the right Tier 1 doc. They do NOT support a decision on their own.
+
+### 3.1 Stack Overflow
+
+Frequently outdated, sometimes wrong, often not version-aware. Use to discover an answer's existence — then verify against Tier 1.
+
+If a Stack Overflow answer points to docs, fetch the docs and cite those instead.
+
+### 3.2 Tutorial blogs (non-maintainer)
+
+Most blog posts are static; the framework moved on. The author may not even remember writing it. Don't cite.
+
+### 3.3 LLM training data
+
+Yours included. Treated as Tier 3 for two reasons: it's stale (months/years), and you can't link to it.
+
+### 3.4 README screenshots from random repos
+
+Someone's `examples/foo` directory isn't authoritative. The framework's official docs are.
+
+## When sources conflict
+
+Common scenario: the official docs say one thing, a maintainer blog says another, an issue thread says yet a third.
+
+Resolution:
+
+1. **Newer doc wins** if the version is the same. Docs get corrected; old blog posts don't.
+2. **Maintainer commitment wins** if it's tracked. An issue closed with `wontfix` or a PR merged with `feat:` is binding signal.
+3. **For grey areas, surface the conflict**. Cite all three and tell the user the authoritative resolution is unclear; ask whether to consult the maintainer directly.
+
+## Examples in practice
+
+### Good — multi-source decision
+
+> Decision: use React 19 `useActionState` for the form submission flow.
+>
+> Rationale: idiomatic since React 19; replaces ad-hoc `useFormState`.
+>
+> Sources:
+> - `[source: https://react.dev/reference/react/useActionState, version: 19.0, retrieved: 2026-05-07]` — Tier 1, official API doc
+> - `[source: https://react.dev/blog/2024/12/05/react-19, retrieved: 2026-05-07]` — Tier 2, maintainer blog explaining the migration
+
+### Bad — Stack Overflow as primary
+
+> Decision: use `useEffect` cleanup with `AbortController` to cancel fetches.
+>
+> Source: a Stack Overflow answer with 1.2k upvotes.
+
+The decision is correct, but the citation isn't authoritative. The fix:
+
+> Source: `[source: https://react.dev/reference/react/useEffect#fetching-data-with-effects, version: 18.3, retrieved: 2026-05-07]` — same conclusion, authoritative origin.
+
+### Bad — version-less citation
+
+> Decision: use `Promise.withResolvers()`.
+>
+> Source: `[source: developer.mozilla.org]`
+
+`Promise.withResolvers()` is Node 22+ / browsers TC39 stage 4. The version matters — the cite is incomplete:
+
+> Source: `[source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers, retrieved: 2026-05-07, runtime-support: Node 22+, Chrome 119+]`

package/scaffold/skills/dw-verify/SKILL.md

@@ -177,7 +177,6 @@ This skill is invoked transparently from:
 - `/dw-bugfix` — before claiming the bug is fixed (original symptom no longer reproduces)
 - `/dw-code-review` — before emitting an APPROVED verdict
 - `/dw-generate-pr` — blocks PR creation if the session has no passing VERIFICATION REPORT post-last-edit
-- `/dw-quick` — before committing the one-off change
 
 Callers should mention this skill in their "Skills Complementares" section so the user sees the dependency.
 

package/scaffold/skills/vercel-react-best-practices/SKILL.md

@@ -144,3 +144,7 @@ Each rule file contains:
 ## Full Compiled Document
 
 For the complete guide with all rules expanded: `AGENTS.md`
+
+## References
+
+- `references/perf-discipline.md` — workflow discipline (measure → identify → fix → verify → guard) that wraps the per-rule recipes above. Use when tackling performance work; cite the metric and tool before applying any rule. Adapted from [`addyosmani/agent-skills/performance-optimization`](https://github.com/addyosmani/agent-skills/tree/main/performance-optimization) (MIT).

package/scaffold/skills/vercel-react-best-practices/references/perf-discipline.md

@@ -0,0 +1,122 @@
+# Performance discipline — measure, identify, fix, verify, guard
+
+> Adapted from [`addyosmani/agent-skills/performance-optimization`](https://github.com/addyosmani/agent-skills/tree/main/performance-optimization) (MIT). The rules below complement the per-rule recipes in `rules/` with a workflow discipline.
+
+The biggest performance mistake is fixing the wrong thing. The second biggest is "fixing" without measuring. This file establishes the workflow that prevents both.
+
+## The five-step loop
+
+### 1. Measure
+
+Don't optimize what you haven't measured.
+
+**Frontend:**
+- Lighthouse / PageSpeed Insights → composite score + breakdown.
+- DevTools Performance tab → flame graph, layout/paint timing.
+- `web-vitals` library → LCP, FID/INP, CLS, TTFB on real users.
+- Bundle analyzer (`next-bundle-analyzer`, `webpack-bundle-analyzer`) → see what's actually shipping.
+
+**Backend:**
+- Application logs with timing (`time-X-took: Yms`).
+- DB query analyzer (`EXPLAIN ANALYZE`, slow query log).
+- APM (Datadog, New Relic, Sentry Performance) for distributed traces.
+- `top` / `htop` / process memory + CPU during load.
+
+**Output:** a baseline number with a unit. "It's slow" is not a baseline. "P95 LCP is 4.8s" is a baseline.
+
+### 2. Identify
+
+Find where the time goes. The flame graph or trace shows it; don't guess.
+
+Common culprits:
+
+| Symptom | Likely cause |
+|---------|--------------|
+| Long initial paint | Large bundle, render-blocking resources |
+| Slow time-to-interactive | Heavy JS execution, hydration cost |
+| Layout shift | Missing dimensions, late-loaded fonts |
+| Slow API response | N+1 query, missing index, expensive computation, external call latency |
+| Memory creep | Listener leak, retained closure, unbounded cache |
+
+The cause must come from data, not pattern-matching. The same symptom can have different causes in different apps.
+
+### 3. Fix
+
+Apply the smallest fix that addresses the identified cause:
+
+- N+1 query → batch with `IN (...)`, single JOIN, or DataLoader.
+- Heavy bundle → code splitting, lazy load, dynamic imports.
+- Re-render storm → `useMemo`, `useCallback`, `memo`, signal-based state.
+- Slow API → cache, precompute, parallelize, move work to background.
+- Layout shift → reserve space (width+height attrs, CSS aspect-ratio).
+
+The `rules/` directory in this skill has tactical recipes for each. Use them when the diagnosis points there.
+
+**Don't apply optimizations preemptively.** `useMemo` everywhere = noise + cost. `memo` everywhere = stale prop bugs.
+
+### 4. Verify
+
+Re-measure with the same instrument from step 1.
+
+- Same scenario, same env (or as close as possible).
+- Multiple runs (perf is noisy; one run is not evidence).
+- Compare against baseline.
+
+If the number didn't change meaningfully (e.g., <10% improvement is below noise floor for most metrics): you fixed the wrong thing. Revert and go back to step 2.
+
+If the number improved but the user-perceived experience didn't: you optimized a metric, not a bottleneck. Rethink what to measure.
+
+### 5. Guard
+
+Prevent regression:
+
+- **Performance budgets in CI:** Lighthouse CI, bundle-size limits per route, P95 latency checks.
+- **Regression test for the specific scenario** that was slow.
+- **Monitoring in production** so future regressions surface from real users (not just CI runs that may not match prod load).
+- **Document the constraint** in code comments at the boundary that must stay fast (e.g., "this loop processes the entire user list; keep it O(n)").
+
+Without guards, every refactor risks reintroducing the bottleneck. The fix decays.
+
+## Frontend-specific patterns
+
+The `rules/` directory provides recipes for: bundle size (barrel imports, dynamic imports, defer third-party), client-side perf (passive listeners, swr dedup, localStorage schema), async patterns (parallel fetches, suspense boundaries, defer awaits), and JS micro-perf. Apply when measurement points there.
+
+**Hierarchy of impact (typical):**
+1. Bundle size — biggest impact for cold loads.
+2. Hydration cost — biggest impact for time-to-interactive.
+3. Network waterfalls — biggest impact for data-heavy pages.
+4. Re-render volume — biggest impact for interactive heavy pages.
+5. JS micro-perf — usually irrelevant unless in a hot loop.
+
+Optimize in this order; don't jump to (5) before (1).
+
+## Backend-specific patterns
+
+| Pattern | When |
+|---------|------|
+| Add database index | Query plan shows full table scan |
+| Batch N queries into 1 | N+1 detected in trace |
+| Cache (Redis, in-memory, edge) | Same expensive computation repeats |
+| Precompute / materialize | Aggregation that runs per-request but updates rarely |
+| Background job | Work doesn't need to block the response |
+| Parallelize independent calls | Trace shows sequential awaits with no dependency |
+| Move to faster runtime / region | Network or CPU is the bottleneck after other fixes |
+
+## When NOT to optimize
+
+- The number isn't actually a problem. "P95 200ms" doesn't need optimization unless your SLA is tighter.
+- The optimization makes the code substantially harder to maintain. A 5% gain isn't worth a 50% complexity increase.
+- The optimized code can't be tested. If perf code can't be regression-tested, the next change will undo it silently.
+- You're optimizing dev-mode performance, not prod. Many tools (React, Next, Vite) have very different hot paths in dev vs prod.
+
+## Anti-patterns
+
+- "Looks slow, let me memo this" — without measurement, this just adds complexity.
+- "Add caching to fix the slow query" — caching hides the bug; the slow query reappears for the next user.
+- Profiling once, optimizing five things, never re-measuring.
+- Setting `useMemo` deps wrong — silently breaks correctness for marginal perf gain.
+- Treating Lighthouse score as the only metric — score can improve without UX improving.
+
+## Integration with dev-workflow
+
+Use with `dw-refactoring-analysis` when flagging perf-related smells: cite the metric, the measurement tool, and the suggested rule from the `rules/` directory. Without those three, a perf "smell" is a guess.

package/scaffold/skills/webapp-testing/SKILL.md

@@ -131,3 +131,8 @@ try {
 ## Helper Functions
 
 Some helper functions are available in [`test-helper.js`](./assets/test-helper.js) to simplify common tasks like waiting for elements, capturing screenshots, and handling errors. You can import and use these functions in your tests to improve readability and maintainability.
+
+## References
+
+- `references/security-boundary.md` — every byte from a browser is potentially attacker-controlled. Test that server-side authorization, validation, and CSRF protection hold even when the UI is bypassed via direct API calls or DevTools manipulation. Adapted from [`addyosmani/agent-skills/browser-devtools`](https://github.com/addyosmani/agent-skills/tree/main/browser-devtools) (MIT).
+- `references/three-workflow-patterns.md` — UI bugs vs network issues vs performance investigations are three distinct testing workflows with different signals and failure modes. Pick the right workflow for the verification you actually need; don't conflate them in a single mega-test. Adapted from the same upstream skill.