@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/research/SKILL.md

@@ -0,0 +1,422 @@
+---
+name: research
+description: >
+  Research current practice with Context7, Firecrawl, and official docs before
+  a non-trivial change: gap analysis and a file-mapped plan, no
+  implementation. Use when "look up current docs" or before anything
+  unfamiliar.
+license: MIT
+effort: high
+---
+
+# research — Production research protocol
+
+**Degree of freedom: MIXED.** Repo-first inventory and official-docs
+order `[LOW freedom — run exactly]`. Which sources to trust and which
+pattern to recommend `[HIGH freedom]`.
+
+Understand the current repo first. Then fetch version-matched official
+docs. Then map findings back to specific files. **Do not implement until
+the user asks or approves.**
+Recognizing a library, tool, or product name is not knowing its current state. Search the name as written and fetch the installed version's docs even when you think you already know the answer — that is the whole point of this skill.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **research** (this) | Current-year, version-matched investigation + gap analysis + plan |
+| `plan-*` | Audit → approved burndown (no implementation) |
+| `docs-adr` | Decision memory after a choice is made |
+| `workflow-onboard` | First-contact repo orientation, not industry research |
+| `complete-everything` | Execute an already-approved plan |
+
+## How to reason
+
+1. **Observe** — installed versions, current files, existing pattern
+2. **Interpret** — what is actually missing vs what just looks old
+3. **Classify** — keep / replace / add / reject (deprecated, CVE, untyped)
+4. **Decide** — one recommended approach mapped to concrete files
+
+## Worked example
+
+> **Observe:** consumer asked whether `npx skills add` overwrites slash
+> commands; pack ships both `commands/*.md` and `skills/*/`.
+> **Interpret:** two installers, two `--all` meanings; Cursor now
+> slash-invokes skills so same-name pairs look duplicated.
+> **Classify:** docs lie (skills add claimed to install commands); npm
+> installer merge-overwrites correctly.
+> **Decide:** keep npm installer as the full-pack path; add `--verify`;
+> promote this protocol from command-only to a skill.
+
+## Self-critique
+
+Before delivering the plan, fail the run if any of these are true:
+
+- Repo files were not read before the first external search
+- Official docs for the *installed* version were skipped when available
+- A recommendation has no source, or only one weak blog post
+- The plan is not mapped to concrete repo paths
+- Implementation started without an explicit user ask
+
+---
+
+## Step 1: Understand the codebase context — before any external search
+
+Before any external research, understand what you're working with.
+
+### 1a. Discover Tech Stack
+
+Read the dependency manifest to get exact library names and versions:
+
+```
+package.json          (Node/JS/TS)
+requirements.txt      (Python)
+pyproject.toml        (Python)
+Cargo.toml            (Rust)
+go.mod                (Go)
+build.gradle          (Java/Kotlin)
+Gemfile               (Ruby)
+```
+
+Extract: framework, major libraries, their exact versions.
+
+### 1b. Read the Existing Implementation
+
+Read the specific file(s) related to the topic being researched, in full — conventions, limitations, and TODOs live outside the obvious lines. Understand:
+
+- What pattern is currently used?
+- What dependencies does it rely on?
+- What are the known limitations or TODOs?
+- What conventions does the project follow?
+
+### 1c. Formulate Research Questions
+
+Write out explicitly:
+
+```
+Current state: [what the project does now]
+Gap/goal: [what needs to improve or be added]
+Specific questions:
+  1. [question about best practice]
+  2. [question about alternative approach]
+  3. [question about edge cases]
+```
+
+---
+
+## Step 2: Context7 — Official Documentation
+
+Fetch current docs for the libraries involved. Use the Context7 MCP (if available).
+
+### Resolve Library ID
+
+```json
+context7:resolve-library-id
+{
+  "libraryName": "<library-name>",
+  "query": "<your specific question>"
+}
+```
+
+### Fetch Documentation
+
+Pick the best match from the resolution results, then:
+
+```json
+context7:query-docs
+{
+  "libraryId": "<selected-id>",
+  "query": "<your specific question>"
+}
+```
+
+Run Context7 for each major library involved. Prefer version-specific IDs when available.
+
+**If Context7 is unavailable**, skip to Step 3 and use Firecrawl to search official documentation sites directly.
+
+---
+
+## Step 3: Firecrawl — Three-Phase Deep Research
+
+Use the `firecrawl` MCP server. The research happens in three phases: broad search, deep scrape, then discovery.
+
+### Phase 1: Broad Search (find what's out there)
+
+Search without scraping first — get URLs and snippets to evaluate:
+
+```json
+firecrawl:firecrawl_search
+{
+  "query": "[library] [topic] best practices [current year]",
+  "limit": 5,
+  "sources": [{ "type": "web" }]
+}
+```
+
+Run 2-3 search queries with different angles:
+
+| Angle | Query Pattern |
+|-------|---------------|
+| Best practices | `[tech] [topic] best practices [current year]` |
+| Implementation guide | `[tech] [topic] production implementation guide` |
+| Common mistakes | `[tech] [topic] common mistakes pitfalls avoid` |
+| Migration/upgrade | `[tech] [topic] migration guide from [old version]` |
+| Security | `[tech] [topic] security OWASP [current year]` |
+| Performance | `[tech] [topic] performance optimization production` |
+
+Use search operators for precision:
+
+- `site:` to target specific docs sites (e.g., `site:react.dev`, `site:nextjs.org`)
+- `""` for exact phrases
+- `-` to exclude irrelevant results
+
+### Phase 2: Deep Scrape (read the best sources thoroughly)
+
+From Phase 1 results, pick the 2-3 most authoritative URLs (official docs, maintainer blogs, engineering blogs). Scrape each for full content:
+
+```json
+firecrawl:firecrawl_scrape
+{
+  "url": "<authoritative-url>",
+  "formats": ["markdown"],
+  "onlyMainContent": true
+}
+```
+
+For extracting specific data points (config options, API parameters, migration steps):
+
+```json
+firecrawl:firecrawl_scrape
+{
+  "url": "<docs-url>",
+  "formats": ["json"],
+  "jsonOptions": {
+    "prompt": "Extract the recommended configuration options and their default values",
+    "schema": {
+      "type": "object",
+      "properties": {
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "recommended": { "type": "string" },
+              "description": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+If a documentation site is large and you're not sure which page has the answer, use `firecrawl_map` first to discover the right page:
+
+```json
+firecrawl:firecrawl_map
+{
+  "url": "https://docs.example.com",
+  "search": "[your topic]",
+  "limit": 20
+}
+```
+
+Then scrape the specific page(s) found.
+
+### Phase 3: Discovery (find reference implementations)
+
+Search for real-world codebases that solved the same problem:
+
+```json
+firecrawl:firecrawl_search
+{
+  "query": "[tech] [topic] example implementation github",
+  "limit": 5,
+  "sources": [{ "type": "web" }]
+}
+```
+
+Also try:
+
+| Discovery Query | Purpose |
+|-----------------|---------|
+| `[tech] [topic] open source example` | Find real implementations |
+| `[tech] [topic] starter template boilerplate` | Find scaffolded patterns |
+| `[tech] [topic] "how we" OR "how I" production` | Find experience reports |
+| `site:github.com [tech] [topic] in:readme` | Find repos directly |
+
+Scrape the README or relevant docs of promising repos to extract their architectural decisions.
+
+---
+
+## Step 4: Gap Analysis (the core of research-driven enhancement)
+
+Compare what the project currently does against what research found. Produce a structured gap analysis:
+
+```
+## Gap Analysis: [Topic]
+
+### What the project does correctly
+- [pattern 1]: aligns with [source] recommendation
+- [pattern 2]: follows current best practice
+
+### What the project is missing
+- [gap 1]: [source] recommends X, project does Y or nothing
+- [gap 2]: [source] warns against current pattern, suggests Z
+
+### Anti-patterns detected
+- [anti-pattern 1]: project uses [old pattern], [source] recommends [new pattern] because [reason]
+
+### New capabilities available
+- [capability 1]: [library] now supports [feature] as of v[X], not yet adopted
+- [capability 2]: [new approach] reduces complexity, project uses legacy pattern
+```
+
+---
+
+## Step 5: Fallback — WebSearch + WebFetch
+
+When Firecrawl MCP is unavailable, use built-in tools with the same three-phase approach:
+
+### Phase 1: Broad Search
+```
+WebSearch(search_term: "[tech] [topic] best practices [current year]")
+```
+
+### Phase 2: Deep Read
+```
+WebFetch(url: "<authoritative-url-from-search>")
+```
+
+### Phase 3: Discovery
+```
+WebSearch(search_term: "[tech] [topic] github example implementation")
+```
+
+---
+
+## Step 6: Synthesize and Decide
+
+### Trust Hierarchy (when sources conflict)
+
+1. Official documentation (highest trust)
+2. Core maintainer posts / RFCs / changelogs
+3. Engineering blogs from major companies (Vercel, AWS, Google, Meta)
+4. GitHub discussions on official repos
+5. Community articles with high engagement (current year, verified working)
+
+### Conflict Resolution
+
+When two authoritative sources recommend different approaches:
+
+1. Check which source matches the project's installed version
+2. Check which approach aligns with the project's existing patterns
+3. Check which approach has fewer trade-offs for the project's scale
+4. If still tied, prefer the simpler approach
+
+### Validation Gates
+
+| Gate | Check |
+|------|-------|
+| Fresh | Published current year or previous year, matches installed version |
+| Secure | No known CVEs, follows OWASP guidelines |
+| Typed | Full TypeScript support, no `any` escape hatches |
+| Tested | Can be unit/integration tested, doesn't break existing tests |
+| Compatible | Works with the project's other dependencies and patterns |
+
+**Reject a pattern if:** it uses a deprecated API, has known vulnerabilities, skips error handling, requires a major refactor with unclear benefit, or conflicts with the project's architecture.
+
+---
+
+## Step 7: Plan Complex Implementations
+
+Plan multi-file architectural migrations directly in the plan: ordered files, intermediate states, side effects. Thinking is native — the Sequential Thinking MCP is not shipped (ADR-0009) and adds nothing here.
+
+Do **not** add Playwright MCP for research or browser checks — use headed `playwright-cli` per `protocol-browser-anti-stall`. Firecrawl stays authenticated; do not switch to the keyless tool subset just to save tokens.
+
+---
+
+## Step 8: Apply to Codebase
+
+Map every research finding to specific, actionable code changes. Do not implement in this skill.
+
+```
+## Implementation Plan
+
+### Changes (ordered by priority)
+
+1. **[file path]** — [what to change and why]
+   - Before: [current pattern]
+   - After: [recommended pattern]
+   - Risk: [low/medium/high] — [explanation]
+
+2. **[file path]** — [what to change and why]
+   ...
+
+### New dependencies (if any)
+- [package@version] — [why needed]
+
+### Breaking changes
+- [description of what breaks and how to migrate]
+
+### Edge cases to handle
+- [edge case 1]
+- [edge case 2]
+
+### Verification
+- [how to verify the change works]
+```
+
+---
+
+## Output Template
+
+After completing research, produce this summary:
+
+```markdown
+## Research: [Topic]
+
+### Context
+- Tech stack: [framework, libraries, versions]
+- Current implementation: [brief description]
+- Research goal: [what we're trying to learn/improve]
+
+### Findings
+[Key patterns and recommendations from research]
+
+### Recommended Approach
+[Pattern name] — [one-line why this is best for this project]
+
+### Gap Analysis
+- Missing: [what the project should add]
+- Replace: [what the project should change]
+- Keep: [what the project already does well]
+
+### Implementation Plan
+[Ordered list of file changes with before/after]
+
+### Gotchas
+- [Edge case or risk 1]
+- [Edge case or risk 2]
+
+### Sources
+- [URL] — [what it provided]
+- [URL] — [what it provided]
+```
+
+---
+
+## Pre-Implementation Checklist
+
+- [ ] Codebase context understood (tech stack, current patterns, specific files read)
+- [ ] Context7 docs fetched (or skipped if unavailable)
+- [ ] Firecrawl broad search completed (2-3 queries)
+- [ ] Firecrawl deep scrape completed (2-3 best URLs)
+- [ ] Discovery search completed (reference implementations found)
+- [ ] Gap analysis produced (current vs recommended)
+- [ ] Sources cross-referenced (3+ sources agree)
+- [ ] Validation gates passed (fresh, secure, typed, tested, compatible)
+- [ ] Implementation plan maps findings to specific files
+- [ ] Edge cases identified

package/skills/test-exploratory/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: test-exploratory
+description: >
+  Headed exploratory QA of a live app as guest, then logged in, with junk
+  input and navigation abuse. Use when "monkey test", "wander like a confused
+  user", or "guest vs logged in". CRUD stories → test-qa. Hostile sweep →
+  test-red-team.
+license: MIT
+---
+
+# test-exploratory — naive-user discovery, two identities
+
+**Degree of freedom: MIXED** — wander and charters `[HIGH freedom]`; driver,
+sessions, and triage `[LOW freedom — run exactly]`. Driver is
+**playwright-cli**, never Playwright MCP. **Three isolated sessions** — never
+share storage.
+
+You drive the **live non-prod app** like a slightly careless user. The job is
+**discovery, not verification**: find the bugs nobody scripted. The sharpest
+bugs live in the **guest vs logged-in diff**. Report only — do not fix in this
+pass. Pair with `protocol-browser-anti-stall`. Hand real bugs to
+`workflow-feedback-to-closure`. Lock a fix later with `test-playwright`.
+Your turn ends with the Phase 3 report after all three identities have run — not after the guest pass, and not with charters still open inside their time-box.
+
+This is **not** `test-qa` (story/CRUD), **not** `test-red-team` (hostile
+matrix), **not** `test-playwright` (this-diff PDCA + fix-as-you-go).
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|:------|:-----|
+| **test-exploratory** (this) | Unscripted wander + junk/nav-abuse + **guest vs authed diff table** |
+| `test-qa` | Story-driven CRUD / smoke — explicitly not a monkey test |
+| `test-red-team` | Adversarial feature×dimension matrix (security/data/perf) |
+| `test-playwright` | Session diff + blast radius; **fixes** inline |
+| `audit-auth-flows` | Static route×gate matrix (code). This skill is the **live probe** |
+| `audit-ux-journeys` | Story completability / IA — not junk submit + double-click |
+| `audit-accessibility` | WCAG / axe only |
+
+## How to reason (before a finding)
+
+1. **Observe** — captured console/network event + identity + snapshot ref
+2. **Interpret** — guest-in-protected, guest-only throw, leakage, or expected deny?
+3. **Classify** — Real bug / UX defect / Flaky / Out of scope (Phase 3 table)
+4. **Severity** — blast radius: auth/money first
+
+## Worked example
+
+> **Observe:** guest session `goto /settings/billing` → 200 + "Update card".
+> Authed same route works. Console clean.
+> **Interpret:** protected billing UI reachable without a session.
+> **Classify:** Real bug — guest-in-protected (live complement to `audit-auth-flows`).
+> **Severity:** critical.
+> **Finding:** guest | billing | guest-in-protected | critical | repro: `-s=explore-guest` goto `/settings/billing`
+
+## Phase 0 — Safety, driver, isolation  [LOW freedom — sessions exact]
+
+- **Non-prod only.** You will submit forms and mash destructive controls. If
+  only prod exists: read-only navigation and say so.
+- **Driver is playwright-cli**, never Playwright MCP:
+
+  ```bash
+  PW="npx --yes @playwright/cli@latest"
+  $PW -s=explore-guest open --headed http://localhost:3000
+  ```
+
+  Read `protocol-browser-anti-stall` first (Rule 0: headed, one action, no
+  `*.spec.ts`). Use **three isolated sessions** — never share storage:
+
+  | Session | Storage | Purpose |
+  |:--------|:--------|:--------|
+  | `-s=explore-guest` | default in-memory (no `--profile`) | anonymous |
+  | `-s=explore-authed` | `state-load` or dedicated `--profile` under `~/.playwright-cli-profiles/` | seeded test account |
+  | `-s=explore-post-logout` | fresh in-memory | prove logout actually cleared state |
+
+  See `protocol-browser-anti-stall/references/playwright-session-coordination.md`.
+- **Instrument before the first click.** After `open`, capture `console`,
+  network/`requests`, and status ≥400. Judge findings against **captured
+  events**, not guesses.
+- **Accessibility tree first.** Click/fill by snapshot **refs** (`e12`). Refs
+  die on the next page change — **re-snapshot after every navigation**
+  ([Playwright Agent CLI snapshots](https://playwright.dev/agent-cli/snapshots)).
+  Use `--depth` or a scoped snapshot on dense pages. Screenshot is a
+  **secondary** modality for layout/grouping (web.dev 2026), not the driver.
+  Vision/coordinates only for canvas or unnamed icons
+  ([vision mode](https://playwright.dev/agent-cli/vision-mode)).
+- **SBTM charters** — copy `references/charter-template.md`. Time-box each
+  identity (30–45 min). Stop when the box ends; record leftovers.
+
+## Phase 1 — Map, then wander (per identity)  [HIGH freedom]
+
+1. **Discover routes** from links + router/sitemap. Build a **per-identity**
+   list (some routes exist only when logged in).
+2. **Exercise the a11y tree** on each page: every button/link/tab/menu/modal;
+   forms three ways (**valid / empty-required / junk** — huge strings, emoji,
+   `<script>`, SQL-ish, negatives, wrong types, whitespace); **double-submit**;
+   dismiss modals three ways (X, Escape, click-outside).
+3. **Abuse navigation** — back/forward after mutations, refresh mid-flow,
+   deep-link inner routes, Back after logout (on the post-logout session).
+4. **One mobile-width pass** on key pages. Layout breakage →
+   `audit-responsive`. Empty/error chrome → `audit-ui-states`. Do not re-audit.
+5. **Short monkey burst** on auth, checkout, and mutating forms only (confused
+   click sequences / races). Skip marketing pages.
+
+Prioritize blast radius: auth, money, account mutation, then the rest.
+
+## Phase 2 — Guest vs logged-in diff (the deliverable)  [HIGH freedom]
+
+Run Phase 1 fully as **GUEST**, then fully as **LOGGED-IN**, then
+**POST-LOGOUT**. Compare. File these in a dedicated table — nothing else in
+the pack produces it:
+
+- **Guest reaches protected things** — route/API/UI that should require auth
+  (live complement to `audit-auth-flows`).
+- **Guest-only breakage** — 500/404/throw for guests, works when authed
+  (null-user). Auth-looking UI that renders for guests then errors on click.
+- **Login/logout transitions** — redirect loops, broken return-to, session
+  not cleared.
+- **State leakage** — cookies, `localStorage`, **`sessionStorage`** (Playwright
+  `storageState` does **not** persist sessionStorage — inspect it explicitly),
+  bfcache/Back showing private data after logout.
+- **Divergent errors** — same action, different failure per identity.
+
+## Phase 3 — Triage (this IS the work)  [LOW freedom — T4; do not skip]
+
+Classify every captured event before it becomes a finding:
+
+| Class | Meaning | Action |
+|:------|:--------|:-------|
+| **Real bug** | Reproducible: uncaught exception, 500, dead control, raw error, guest-in-protected, hang, data-loss on double-submit | File with repro + identity + evidence |
+| **UX defect** | Works but wrong (silent fail, no loading/error) | Route to `audit-ui-states` / `audit-ux-journeys` |
+| **Flaky** | Failed once | **Re-run once** before filing. Do not file flakes |
+| **Out of scope** | WCAG, pixel polish, load | Hand off; do not duplicate |
+
+Severity by blast radius (auth/money first). Do not generate a Playwright
+spec dump and call the app "covered" — that is shallow comprehensive coverage.
+
+## Self-critique before reporting
+
+- **Identity + evidence** — every row names who and shows the artifact
+- **Flakes** — re-run once before filing
+- **Handoff** — WCAG / pixel / load were not filed here
+- **Guest** — never used `--profile`
+
+## Definition of Done
+
+- [ ] Non-prod (or read-only + said so)
+- [ ] Three isolated CLI sessions; guest never used `--profile`
+- [ ] Listeners attached before interaction; traces/screenshots per identity
+- [ ] Charters filled; leftovers listed
+- [ ] Route lists per identity; high-blast-radius monkey pass done
+- [ ] Guest + authed + post-logout runs
+- [ ] Guest-vs-authed **diff table** produced
+- [ ] Events triaged; flakes re-run; each real bug has repro + identity + evidence
+- [ ] Honest skip list (MFA, paid flows, external redirects)
+
+## Output format
+
+1. **Run summary** — target, charters, routes per identity, skips
+2. **Findings table** — id | identity (guest/authed/both) | area | type | severity | repro | evidence
+3. **Guest-vs-logged-in diff** — protected-reachable, guest-only breakage, transitions, leakage
+4. **Console/network** — recurring errors, ≥400, hangs
+5. **Handoffs** — `audit-responsive` · `audit-ui-states` · `audit-auth-flows` · each bug → `workflow-feedback-to-closure` → later `test-playwright`
+
+Present the report. Do not fix in this pass.

package/skills/test-exploratory/references/charter-template.md

@@ -0,0 +1,29 @@
+# SBTM charter template (test-exploratory)
+
+One charter = one time-boxed session + one identity. Copy a row, fill it, debrief.
+
+## Charter card
+
+| Field | Value |
+|:------|:------|
+| Charter | e.g. Guest: public routes + auth walls + public forms |
+| Identity | guest / authed / post-logout |
+| Session name | `explore-guest` / `explore-authed` / `explore-post-logout` |
+| Time box | 30–45 min (stop when the box ends; record leftovers) |
+| Target URL | non-prod only |
+| In scope | routes / areas |
+| Out of scope | MFA walls, paid checkout, production data, WCAG (→ `audit-accessibility`) |
+| Stop when | time box ends **or** high-blast-radius areas done |
+
+## Debrief (required)
+
+- Areas covered / not covered
+- Real bugs (id list)
+- Flakes re-run? (yes/no)
+- What was **not** reached and why
+
+## Suggested charters (run both identities)
+
+1. **Guest — walls & public surface** — deep-link protected URLs, public forms (valid/empty/junk), login entry.
+2. **Authed — mutate & navigate** — every control on high-blast-radius pages, double-submit, back/forward, refresh mid-flow.
+3. **Post-logout — isolation** — fresh session, no profile; hit last authed URL + Back; confirm no private cache/cookies/`sessionStorage`.