Senior QA (the orchestrator)

The Senior QA is the top-level agent the orchestrator. It’s implemented in src/core/orchestrator.ts.

Senior QA doesn’t explore pages or generate tests. It makes decisions:

1. What to test?: maps a natural-language change description to affected pages
2. How much?: full regression vs iterative vs smoke vs targeted
3. Who runs it?: spins up Junior QA subagents per page
4. Is it safe?: enforces terminal guards, budget caps (planned for a future release), scope confirmations
5. What did we learn?: aggregates per-page reports into one unified artifact
6. What changed?: diffs against the knowledge base

Responsibilities

Responsibility	Implemented in
Load config, credentials, KB	src/utils/config.ts, src/kb/manager.ts
Run phases in the correct order	src/core/orchestrator.ts
Decide iterative vs full vs smoke	src/core/scope-decider.ts
LLM-backed scope inference	src/core/scope-inferrer.ts
Human-in-the-loop checkpoint	src/utils/prompts.ts
Delegate to Junior QA	src/claude/delegate.ts
Run smoke checks	src/agents/smoker.ts
Produce the unified report	src/agents/reporter.ts
Persist models + bugs + flaky registry	src/kb/manager.ts

The scope decision

This is the defining decision Senior QA makes. When you run:

nitpick run --scope iterative --change"I modified the task form"

Senior QA:

1. Reads the change description
2. Calls the configured LLM (with a fast model like Haiku) with the change description, the full page graph, and your known flows
3. Gets back structured JSON: affected_pages[] with confidence and reason
4. Presents the proposal to you, not blindly, but with reasons
5. Waits for your confirmation

If the LLM is unavailable or returns nothing parseable, Senior QA falls back to keyword overlap against page IDs and URLs.

Why”Senior”?

Because the decisions Senior QA makes are the ones a senior QA engineer makes on a team:

• “What’s the blast radius of this change?”: scope inference
• “Is this worth deep-testing?”: iterative vs smoke
• “Who should own this?”: which subagent to delegate to
• “Is this a new bug or the one we saw last week?”: bug dedupe
• “Should we ship?”: unified report with pass/fail summary

Juniors execute. Seniors route. That’s the same in real orgs and in Nitpick.

What Senior QA doesn’t do

• Does NOT explore pages, that’s Junior QA
• Does NOT generate Playwright tests, that’s Junior QA
• Does NOT classify individual test failures, Junior QA’s retry loop owns that
• Does NOT manage individual runs’ state, workflow.ts does