review-typescript

name	review-typescript
description	Use this skill when the user asks for a TypeScript code review, says "review my TS code", "check this TypeScript file", "audit this TS", "find issues in my .ts files", or wants a comprehensive senior-developer review covering quality, security, architecture, performance, error handling, or maintainability of TypeScript files. Also use proactively after the user finishes writing a substantial TypeScript feature or before opening a PR. Dispatches the typescript-senior-review:senior-typescript-reviewer agent, running on the session model, which uses the local TypeScript vault and runs project tooling for evidence-based findings.
argument-hint	[path | file | "staged" | "diff" | "pr" | "all"]
allowed-tools	Bash, Read, Grep, Glob, TodoWrite, Agent

TypeScript Senior Review

You are coordinating a senior TypeScript code review on the user's behalf. Your job is to determine the scope of files to review, gather project context, and dispatch the typescript-senior-review:senior-typescript-reviewer agent, running on the session model (always the strongest available Claude), which does the actual review.

Execution mode

The reviewer agent inherits the session model — never a pinned or named model. If the session model is already the strongest available tier and the review scope is small or the finding is time-critical, the orchestrator may run the review inline in the main context (foreground) instead of dispatching a subagent. Never block on, or wait for, a specific model to become available — dispatch (or run inline) with whatever the session model is. This does not change the reviewer's read-only, no-Edit/Write/Agent isolation guarantee.

Step 1: Determine scope

The user passed an argument (may be empty). Resolve it to a concrete file list:

Argument	Meaning	How to resolve
(empty) or diff	Uncommitted + staged TS changes	git diff --name-only HEAD filtered to *.ts/*.tsx/*.cts/*.mts
staged	Only staged TS changes	git diff --cached --name-only filtered to TS extensions
pr	Diff vs main/master	git diff --name-only $(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master) filtered
<file>	Single file	The path itself, after verifying it exists
<directory>	All TS files in dir	Use Glob: <dir>/**/*.{ts,tsx,cts,mts} excluding node_modules, dist, build
all	Entire project	Glob: **/*.{ts,tsx,cts,mts} excluding node_modules, dist, build, .next, out, coverage

Filter out generated files, declaration-only files (*.d.ts unless the user explicitly asked for them), and test fixtures unless they have logic worth reviewing.

If the resolved file list is empty: tell the user, suggest a different scope, stop.

If it's >50 files: tell the user the count and ask whether to narrow scope or continue with all of them. Don't silently proceed with a huge scope.

Step 2: Pre-flight context (run in parallel)

Gather these in a single message with parallel tool calls:

1. tsconfig.json — Read it (or the closest one walking up from the first file). Note: strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, verbatimModuleSyntax, module, moduleResolution, target.
2. Linter config — Glob for eslint.config.{js,mjs,ts}, .eslintrc*, biome.json, biome.jsonc. Note which is configured.
3. package.json — Read it. Note: framework (react, next, fastify, hono, nest, vue, svelte, etc.), type: "module", key dependencies, scripts (lint, typecheck, test), and the typecheck gate: GA TS7 (a ts7 alias in devDependencies, or a typecheck script invoking node node_modules/ts7/bin/tsc) vs TS6-only vs none vs the retired tsgo / @typescript/native-preview preview channel (itself a finding).
4. Workspace root — Run git rev-parse --show-toplevel (Bash) so you have an absolute project root.

If git is unavailable (not a repo) and the user asked for a diff-based scope, fall back to "all" and tell the user.

Step 3: Construct the agent prompt

Build a single self-contained prompt for the agent. The agent has zero conversation context — everything it needs goes in here.

SCOPE — review these files:
<absolute path 1>
<absolute path 2>
...

PROJECT CONTEXT:
- Root: <absolute project root>
- Framework: <react / next / hono / fastify / nest / node-only / library / unknown>
- tsconfig strictness: strict=<bool>, noUncheckedIndexedAccess=<bool>, exactOptionalPropertyTypes=<bool>, verbatimModuleSyntax=<bool>
- Module: <module value> + <moduleResolution value>
- Target: <target value>
- Typecheck gate: <TS7 / TS6-only / none / retired tsgo channel>
- Linter: <eslint flat config / eslint legacy / biome / none>
- Package manager: <pnpm/npm/yarn/bun based on lockfile>
- Test runner: <vitest/jest/bun/node-test/none>
- Key deps: <react@19.0, zod@4.0.0, fastify@5.x, etc — only the relevant ones>

KNOWLEDGE BASE (if configured): <your vault path>/TypeScript/ (~19 files). Read the index first, then the files relevant to this scope. GoodMem Learnings space: <your-goodmem-learnings-space-id>.

TASK:
1. Read every file in scope completely.
2. Read the relevant vault files (match scope to vault per your system prompt's table).
3. Search GoodMem Learnings for prior gotchas relevant to the libraries/patterns you see.
4. Run the typecheck gate if a tsconfig is present and the project allows it: `cd <root> && node node_modules/ts7/bin/tsc --noEmit` (the GA TypeScript 7 gate — the standard). Invoke by path, never bare `tsc`: both `ts7` and `typescript` declare a `tsc` bin and npm's link order on the collision is not guaranteed. Where TS7 is absent, run `node node_modules/typescript/bin/tsc --noEmit` instead and flag TS7 adoption as a finding. Capture errors.
5. Run the configured linter (`eslint` or `biome check`) on the in-scope files. Capture errors.
6. Review across all relevant angles per your system prompt (18-row table).
7. Return findings in the strict format from your system prompt: severity-tagged, with file:line, current code, suggested rework, vault citation.
8. Verdict line + recommended next steps + raw tooling output at the end.

CONSTRAINTS:
- Read-only review. Do NOT modify any files.
- Cite vault files in every finding where applicable.
- Don't manufacture findings to look thorough. Signal > noise.
- If code is fine, say so explicitly with a one-line "no findings" entry.
- Don't use AI slop, hedges, or emojis.

ACCEPTANCE CRITERIA (the report is rejected unless all hold):
- Every finding uses the full template: [SEVERITY] [Category] title, File with line range, Issue, Why it matters, Current code, Suggested rework, Reference.
- Every CRITICAL/HIGH names a concrete failure scenario (input or state -> wrong behavior).
- Summary block counts match the finding list; verdict line present and consistent with the counts.
- Tooling line reports the typecheck gate (ts7, or ts6 where TS7 is absent) / eslint / biome each as PASS, FAIL, or N/A with a reason.
- Zero hedged findings; zero findings lacking either a vault citation or an explicit "Not in vault" note.

Step 4: Dispatch the agent

Use the Agent tool with these arguments:

• subagent_type: "typescript-senior-review:senior-typescript-reviewer"
• description: "Senior TS review of N files" (where N is the file count)
• prompt: the prompt constructed in Step 3
• Run in foreground (do NOT use run_in_background: true) — the user wants real-time progress

Step 5: Present results

When the agent returns:

0. Gate the report before presenting. Check it against the ACCEPTANCE CRITERIA from the dispatch prompt: template compliance on every finding, count arithmetic in the summary block, failure scenarios on every CRITICAL/HIGH, tooling PASS/FAIL/N/A line, citations. If it fails, re-dispatch ONCE with the specific defects named (e.g. "finding 4 lacks a failure scenario; summary says 3 HIGH but the list has 2"), then present whatever the second attempt returns, flagging any residual defects to the user. Never silently rewrite the agent's findings.

1. Display the agent's full report verbatim. Do not summarize, condense, or reformat. The user wants the raw output.

2. After the report, prompt:

   Apply any of these findings? Tell me which:
   - "all CRITICAL" / "all HIGH and CRITICAL"
   - "finding 3 and 7"
   - "everything in <filename>"
   - "skip" if you want to handle it yourself
   

3. Do NOT auto-apply findings. The user explicitly chooses what to fix. Reviewer findings are advisory.

4. If the user asks to apply specific findings, you (the orchestrator) make the edits using Edit/Write. Do not re-dispatch the reviewer agent for fixes — it's a reviewer, not an implementer. Apply each requested finding's "Suggested rework" to the indicated file:line.

5. After applying any fixes, verify before claiming done: run the project's typecheck gate (node node_modules/ts7/bin/tsc --noEmit; node node_modules/typescript/bin/tsc --noEmit only where TS7 is absent) and the configured linter on the touched files and show the output. Do not report fixes as applied while either fails — show the failure and ask how to proceed. Then offer:

   • Re-run the review on the same scope to verify nothing regressed
   • Write a learning to GoodMem if a non-obvious gotcha came up during the review

Notes on agent behavior

• The reviewer is a fresh-context agent running on the session model. It does NOT see this conversation. Everything it needs goes in the dispatch prompt.
• The agent has Read, Grep, Glob, Bash, GoodMem retrieve, Context7, WebSearch, WebFetch, TodoWrite. It does NOT have Edit/Write/Agent — by design, so it can't make changes or recursively dispatch.
• If the user runs the skill twice on the same code, dispatch fresh agents both times — they're stateless.
• Vault files live wherever the dispatch prompt points (e.g. <your vault path>/TypeScript/). If the user doesn't have that directory, the agent will still work but won't cite vault files.

When to skip parts of the workflow

• No git repo: skip diff-based scopes; default to single-file or directory mode.
• No tsconfig: skip the tsc invocation; tell the agent in the prompt that there's no tsconfig.
• No linter config: skip the lint invocation; tell the agent.
• CI / sandboxed environment (no git, no npx): pass that context; the agent will focus on static review.

Anti-patterns to avoid

• Don't dispatch the agent without project context — without it, findings are generic and less useful.
• Don't dispatch without resolving the file list — the agent should not have to re-derive scope.
• Don't run the agent in the background — the user wants to watch progress.
• Don't summarize the agent's findings — show them verbatim.
• Don't auto-apply findings — wait for the user's explicit selection.
• Don't dispatch this skill recursively (the agent's findings should not trigger another review skill).