feat: create qa agent skill for detailed code review

.claude/skills/qa-agent/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: qa-agent
+description: "Run a full QA review of this codebase. Traces cross-file impact, checks framework best practices, security, performance, and accessibility. Use /qa-agent for full review, /qa-agent [filepath] for targeted review, /qa-agent --diff for changed files only, /qa-agent --hotspots for most-changed files only."
+allowed-tools: Read, Grep, Glob, Bash
+memory: project
+---
+
+# QA Agent
+
+Use this skill to run a production QA review for the Keploy docs repository. This is a Docusaurus 3 documentation site with heavy SEO customization, versioned docs, custom theme overrides, autogenerated sidebar behavior for current docs, and versioned sidebar JSON for archived docs.
+
+## Required Startup Reads
+
+Before reviewing anything, always read these files first:
+
+1. `context/codebase-map.md`
+2. `context/hotspots.md`
+3. `context/known-suppressions.md`
+4. `context/ignore.md`
+
+Then load the rules that apply to the current target:
+
+1. `rules/framework.md`
+2. `rules/security.md`
+3. `rules/performance.md`
+4. `rules/content.md`
+5. `rules/seo.md`
+6. `checklists/pr-review.md`
+7. `checklists/accessibility.md`
+8. `checklists/seo.md`
+
+Load `rules/typescript.md` when reviewing:
+
+1. any `.ts` or `.tsx` file
+2. any PR that introduces TypeScript
+3. any docs page whose primary risk is a fenced TypeScript example
+
+## Argument Parsing
+
+Parse `$ARGUMENTS` exactly once before doing any review work.
+
+### No arguments
+
+Review `git diff HEAD --name-only`.
+
+If that returns no files, fall back to the 10 most recently changed tracked files:
+
+```bash
+git log --name-only --format="" -n 20 | awk 'NF' | awk '!seen[$0]++' | head -10
+```
+
+### Single file path
+
+If `$ARGUMENTS` is a path like `src/theme/DocItem/index.js` or `versioned_docs/version-4.0.0/running-keploy/public-api.md`, review that file and every file impacted by it.
+
+### `--diff`
+
+Review only files from:
+
+```bash
+git diff HEAD --name-only
+```
+
+### `--full`
+
+Review the entire codebase, but prioritize in this order:
+
+1. `context/hotspots.md`
+2. changed custom theme files under `src/theme/`
+3. shared components under `src/components/`
+4. configuration files such as `docusaurus.config.js`, `sidebars.js`, `netlify.toml`, `vercel.json`
+5. versioned docs under `versioned_docs/`
+
+### `--hotspots`
+
+Review only the files listed in `context/hotspots.md`, top to bottom.
+
+## File Selection Rules
+
+Always remove ignored paths and generated artifacts listed in `context/ignore.md`.
+
+When the target is a docs file, also review:
+
+1. its sidebar configuration path
+2. nearby shared MDX components under `docs/components/`
+3. any linked images or static assets it introduces
+4. any matching versioned sidebar JSON file when the doc is versioned
+
+When the target is a theme or config file, also review:
+
+1. direct dependents
+2. pages that rely on it
+3. content that is affected by its rendering behavior
+
+## Parallel Subagents
+
+Spawn these three subagents in parallel with the Task tool after resolving the initial file list.
+
+### Subagent A
+
+Agent file: `agents/codebase-explorer.md`  
+Subagent type: `Explore`
+
+Prompt:
+
+```text
+Read the file(s) being reviewed. Identify all import/export relationships. Which other files import from these files? Which files do these files import from? Return a structured dependency map.
+```
+
+### Subagent B
+
+Agent file: `agents/impact-tracer.md`  
+Subagent type: `general-purpose`
+
+Prompt:
+
+```text
+Given the files being reviewed: [list]. Use Grep and Glob to find every file in the project that imports from or references these files. Also check for dynamic imports, re-exports, and barrel files (index.ts/index.tsx/index.js). Return a list of impacted files with their relationship type.
+```
+
+### Subagent C
+
+Agent file: `agents/qa-reviewer.md`  
+Subagent type: `general-purpose`  
+Memory: `project`
+
+Prompt:
+
+```text
+Load rules from rules/ relevant to this project. Load relevant checklists. Review the target files + any impacted files identified by Subagent B. Apply all rules. Return structured findings.
+```
+
+## Review Procedure
+
+1. Resolve the target file list from `$ARGUMENTS`.
+2. Remove ignored and generated files.
+3. Launch the three subagents in parallel.
+4. Wait for all three results.
+5. Merge Subagent A dependency data with Subagent B impact data.
+6. Ask Subagent C findings to respect `context/known-suppressions.md`.
+7. Apply higher scrutiny to changed files and hotspot files.
+8. Apply lower scrutiny to impacted dependents:
+   check for breakage, broken imports, sidebar drift, broken internal links, metadata regressions, and rendering regressions, but do not spend time on style-only issues there.
+9. Assemble the final report with `templates/report.md`.
+10. Write the report to `qa-reports/YYYY-MM-DD-HH-MM.md`.
+11. Print a terminal summary with total findings by severity.
+
+Use this report path pattern:
+
+```bash
+mkdir -p qa-reports
+REPORT_PATH="qa-reports/$(date '+%Y-%m-%d-%H-%M').md"
+```
+
+## Severity Model
+
+Use these severities only:
+
+1. `blocking`
+2. `warning`
+3. `suggestion`
+4. `nitpick`
+
+Treat these as blocking in this repository:
+
+1. broken internal docs links
+2. orphaned docs that will not appear in navigation
+3. missing required frontmatter on new docs
+4. unsafe secret exposure in config, scripts, or docs examples
+5. SEO regressions on strategic docs pages that remove canonical URL, description, or social image coverage already supported by the theme
+
+## Repository-Specific Review Focus
+
+This repository is not a generic React app. Bias review time toward:
+
+1. Docusaurus config correctness in `docusaurus.config.js`
+2. theme overrides under `src/theme/`
+3. shared component barrel usage in `src/components/index.js`
+4. versioned docs integrity in `versioned_docs/`
+5. sidebar discoverability through autogenerated current sidebars and `versioned_sidebars/*.json`
+6. SEO metadata rendered by `src/theme/DocItem/index.js`
+7. external scripts and browser globals under `static/js/` and `static/scripts/`
+
+## Output Requirements
+
+The final output must:
+
+1. use the structure from `templates/report.md`
+2. include changed files and cross-file impact
+3. call out ignored files
+4. summarize severity counts
+5. clearly distinguish direct findings from inferred impact
+
+If no findings exist, still produce a report with:
+
+1. severity counts set to zero
+2. reviewed files listed
+3. impacted files listed
+4. skipped files listed
+5. a `Passed gate checklist` section referencing `checklists/pr-review.md`

.claude/skills/qa-agent/agents/codebase-explorer.md

@@ -0,0 +1,53 @@
+# Codebase Explorer
+
+Type: `Explore`  
+Mode: read-only
+
+## Purpose
+
+Map the repo shape around the target files without dumping raw file contents. This agent exists to answer dependency and structure questions fast.
+
+## What To Inspect
+
+1. The target file list.
+2. Parent directories of those files.
+3. `context/codebase-map.md` for global repo structure.
+4. `src/components/index.js` and any nearby `index.js` barrel files.
+5. `src/theme/` overrides when the target affects rendering.
+6. `docusaurus.config.js`, `sidebars.js`, and `versioned_sidebars/*.json` when the target is docs or config.
+
+## Required Tasks
+
+1. Map the local directory structure around the target files.
+2. Identify the router/content system in use:
+   this repo is Docusaurus, so confirm whether the target participates in docs routing, static pages, theme overrides, or static assets.
+3. Find barrel files:
+   `index.ts`, `index.tsx`, `index.js`, `index.jsx`.
+4. Identify shared component and utility patterns.
+5. Identify whether the target participates in:
+   docs rendering, navbar/footer config, sidebar generation, SEO metadata, or static client scripts.
+
+## Output Format
+
+Return a compact JSON-like summary with these keys:
+
+```text
+{
+  repoType: "",
+  targetFiles: [],
+  localDirectories: [],
+  routerPattern: "",
+  barrelFiles: [],
+  importsFromTarget: [],
+  importsUsedByTarget: [],
+  sharedPatterns: [],
+  notes: []
+}
+```
+
+## Constraints
+
+1. Do not return raw file dumps.
+2. Keep entries compact and path-focused.
+3. Prefer exact paths over prose.
+4. If a relationship is inferred rather than directly observed, label it as inferred.

.claude/skills/qa-agent/agents/impact-tracer.md

@@ -0,0 +1,69 @@
+# Impact Tracer
+
+Type: `general-purpose`
+
+## Purpose
+
+Given changed files, trace every place in the repository that could break because of them.
+
+## Inputs
+
+You will receive a list of changed or target files.
+
+## Search Procedure
+
+1. For each target file, search for:
+   ES module imports, CommonJS `require`, MDX imports, and dynamic imports.
+2. Search for re-exports through barrel files:
+   `index.ts`, `index.tsx`, `index.js`, `index.jsx`.
+3. Search for indirect references:
+   exported identifiers, component names, utility names, frontmatter IDs, doc IDs, and slugs.
+4. Search config and navigation references:
+   `docusaurus.config.js`, `sidebars.js`, `versioned_sidebars/*.json`, `static/_redirects`, `netlify.toml`, `vercel.json`, GitHub workflows.
+5. When a docs page changes, also check:
+   related images in `static/`, linked docs, and adjacent versioned docs with the same topic.
+
+## Special Handling For This Repo
+
+1. `src/components/index.js` is a barrel file and must be checked for re-export impact.
+2. `src/theme/DocItem/index.js` changes can affect all docs pages.
+3. `docusaurus.config.js` changes can affect navbar, footer, SEO metadata, versioning, sitemap behavior, and broken-link enforcement globally.
+4. Current docs rely on autogenerated sidebar behavior from `sidebars.js`; versioned docs also rely on `versioned_sidebars/*.json`.
+
+## Output Format
+
+Return exactly this structure:
+
+```text
+{
+  changedFiles: [],
+  directDependents: [
+    { file: "", relationship: "" }
+  ],
+  indirectDependents: [
+    { file: "", relationship: "" }
+  ],
+  configReferences: [
+    { file: "", relationship: "" }
+  ]
+}
+```
+
+## Relationship Labels
+
+Use labels such as:
+
+1. `imports`
+2. `re-exported-through`
+3. `dynamic-import`
+4. `referenced-by-config`
+5. `linked-from-doc`
+6. `shares-asset`
+7. `same-topic-versioned-doc`
+8. `rendered-by-theme-override`
+
+## Constraints
+
+1. Do not include ignored/generated files from `context/ignore.md`.
+2. Prefer exact path matches and identifier matches over broad guesses.
+3. Call out uncertainty when an indirect dependency is inferred.

.claude/skills/qa-agent/agents/qa-reviewer.md

@@ -0,0 +1,62 @@
+# QA Reviewer
+
+Type: `general-purpose`  
+Memory: `project`
+
+## Purpose
+
+Review target files and impacted files using the project rules, while avoiding false positives from known suppressions and ignored paths.
+
+## Required Reads
+
+Always read:
+
+1. `context/known-suppressions.md`
+2. `context/ignore.md`
+3. `rules/framework.md`
+4. `rules/security.md`
+5. `rules/performance.md`
+6. `rules/content.md`
+7. `rules/seo.md`
+8. `checklists/pr-review.md`
+9. `checklists/accessibility.md`
+10. `checklists/seo.md`
+
+Conditionally read:
+
+1. `rules/typescript.md` for `.ts`, `.tsx`, or TypeScript-heavy code examples
+
+## Review Scope
+
+1. Apply full scrutiny to target files.
+2. Apply lower scrutiny to impacted files from `impact-tracer`:
+   only look for breakage, import drift, navigation drift, metadata drift, content regressions, and unsafe patterns.
+3. Skip any file or pattern listed in `context/ignore.md`.
+4. Skip any already-known suppression listed in `context/known-suppressions.md` unless the suppression itself is the bug.
+
+## Output Schema
+
+For every finding, output exactly:
+
+```text
+{ severity: "blocking|warning|suggestion|nitpick", file: "", line: "", rule: "", what: "", why: "", fix: "" }
+```
+
+## Review Priorities For This Repo
+
+1. Broken internal links are blocking.
+2. Missing required docs frontmatter is blocking on new content.
+3. Navigation orphaning is blocking.
+4. SEO regressions in shared theme/config files are high severity.
+5. Static browser scripts under `static/js/` and `static/scripts/` require security scrutiny because they execute on every page load.
+6. Theme overrides under `src/theme/` require regression scrutiny because they affect site-wide rendering.
+
+## Memory Updates
+
+When you discover a repeatable project-specific pattern not already captured in the rules, update project memory with a compact note such as:
+
+1. file pattern
+2. why it exists
+3. what not to flag in future reviews
+
+Do not store one-off style preferences that are not consistently used.

.claude/skills/qa-agent/checklists/accessibility.md

@@ -0,0 +1,10 @@
+# Accessibility Checklist
+
+- [ ] Every new image has descriptive alt text or is explicitly decorative
+- [ ] Headings follow a valid hierarchy
+- [ ] Link text is meaningful out of context
+- [ ] Interactive components remain keyboard reachable
+- [ ] Buttons and icon-only controls have accessible names
+- [ ] Color-only meaning is avoided in screenshots, callouts, and custom UI
+- [ ] Embedded media has surrounding explanatory text
+- [ ] Code blocks, tabs, and accordions remain usable with screen readers