expert-notes

What It Does

Reads ONE expert's brief and writes that expert's request-time notes: the requirements the request implies, the invariants it must never break, the acceptance behaviour it should show, the risks it carries, and the questions only a human can answer. Each expert is a lens over the same procedure, not a separate skill: the db-expert looks for tables, indexes and migration safety; the security-auditor looks for who may act and who must not; the ux-ui-analyst looks for the six screen states; and so on. The lens is the only thing that changes.

It decides from the brief alone — the request, the grounding pointers, the label — never the whole repo. The pipeline script validates what comes back against the roster, assigns stable ids, and merges it; this skill does the reading and judgement, the script does the checking.

Use This When

• The spec pipeline is running with the expert roster on (spec_pipeline_experts_enabled), the expert-need-detector has named the experts, and the pipeline has written one brief per expert. Run this skill once per brief.

Do not run this when the experts flag is off — with it off the pipeline is byte-identical to v1 and this skill never runs. Do not invent a role: you write as the role in the brief.

Inputs

• role — required. The expert role you are writing as. Read that role's lens in references/lenses/<role>.md (for example references/lenses/db-expert.md) and apply it.
• brief_path — required. The brief the pipeline wrote. It carries the request text, the ticket acceptance criteria when present, the grounding terms and references (pointers, never file bodies), the clarity label and its signals, and the token budget you are granted.

Procedure

1. Read the brief at brief_path. Read your lens in references/lenses/<role>.md.
2. Decide from the request and the grounding only. Do not read the whole repo.
3. Write findings about concrete targets — a table, an endpoint, a screen, a journey step — each about ONE target and making ONE claim. Mark each finding's kind and severity; see references/finding-kinds.md for what each kind becomes in the spec.
4. Phrase every question as a PipelineQuestion: business words, options phrased as outcomes, and the grounding reference it is grounded in (or null). Ask only what the project's own docs cannot answer.
5. Report the tokens you spent. Stop when the budget in the brief is reached — findings may be empty (you looked and had nothing to add: a valid, cheap outcome).
6. Validate the file with scripts/lint-output.sh, then hand it to the pipeline: paqad-ai spec pipeline experts notes <file>. That runs the deterministic guard (src/spec-pipeline/experts/notes.ts) — an unknown role, kind or severity, or a question in jargon, is refused there; do not re-implement that check.