expert-notes
Reads one expert's brief and, through that expert's lens, writes short request-time notes for the spec pipeline: what the request must do, must never break, and still leaves undecided, as findings plus plain-language questions. One runner skill with a lens per expert (db, security, ui, qa-engineer, agent-orchestrator and the rest), so the procedure is shared and only the lens differs; the qa-engineer note also carries the spec compliance and quality verdicts. The pipeline script validates the output against the roster and never decides. Use when the spec pipeline runs with the expert roster on and an expert on the roster, or a High Table seat given one role, needs its note, findings, questions or verdicts written from its brief (phase 2 of the spec pipeline; the TS guard is src/spec-pipeline/experts/notes.ts).
- License 许可
- MIT
- 所属仓库
- Eliyce/paqad-ai
- 最近更新
- 2026-11-13
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- expert-notes
- metadata
- { "cacheable": "false", "model_tier": "reasoning", "paqad-meta": "skill.meta.yaml", "output_format": "json" }
- description
- Reads one expert's brief and, through that expert's lens, writes short request-time notes for the spec pipeline: what the request must do, must never break, and still leaves undecided, as findings plus plain-language questions. One runner skill with a lens per expert (db, security, ui, qa-engineer, agent-orchestrator and the rest), so the procedure is shared and only the lens differs; the qa-engineer note also carries the spec compliance and quality verdicts. The pipeline script validates the output against the roster and never decides. Use when the spec pipeline runs with the expert roster on and an expert on the roster, or a High Table seat given one role, needs its note, findings, questions or verdicts written from its brief (phase 2 of the spec pipeline; the TS guard is src/spec-pipeline/experts/notes.ts).
02 资源文件 20
- 参考文档agents/openai.yaml357 B
- 资产文件assets/output.template.md1.3 KB
- 参考文档references/finding-kinds.md1.4 KB
- 参考文档references/lenses/agent-orchestrator.md1.5 KB
- 参考文档references/lenses/application-architect.md3.1 KB
- 参考文档references/lenses/data-modeler.md2.1 KB
- 参考文档references/lenses/db-expert.md2.3 KB
- 参考文档references/lenses/devops-engineer.md2.0 KB
- 参考文档references/lenses/integration-architect.md2.0 KB
- 参考文档references/lenses/market-researcher.md1.5 KB
- 参考文档references/lenses/performance-analyst.md2.1 KB
- 参考文档references/lenses/product-owner.md2.4 KB
- 参考文档references/lenses/qa-engineer.md2.8 KB
- 参考文档references/lenses/security-auditor.md2.2 KB
- 参考文档references/lenses/skill-orchestrator.md1.5 KB
- 参考文档references/lenses/solution-architect.md2.2 KB
- 参考文档references/lenses/user-flow-writer.md2.3 KB
- 参考文档references/lenses/ux-ui-analyst.md2.2 KB
- 脚本scripts/lint-output.sh2.8 KB
- 参考文档skill.meta.yaml408 B
03 SKILL.md 正文
What It Does
Writes ONE expert's request-time notes from its brief: 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 this one procedure (the db-expert looks for tables, indexes and migration safety, the security-auditor for who may act), and the lens is the only thing that changes. It decides from the brief alone, never the whole repo; the pipeline script validates, numbers and merges what comes back.
Use This When
- The spec pipeline is running with the expert roster on (
spec_pipeline_experts_enabled), theexpert-need-detectorhas named the experts, andexperts recordhas put them on the roster. Run this skill once per expert, with the brief theexperts briefverb prints for it. - You run as one High Table seat (a
paqad-expertsubagent) given one role. Then a note covers that role only: write one note, hand it toexperts notes, and the verb merges it beside the other seats' notes without touching them.
Do not run this when the experts flag is off; the skill never runs then. Do not invent a role: you write as the role in the brief.
Inputs
role: required. The expert role you are writing as; apply its lens.brief: required. Print it withpaqad-ai spec pipeline experts brief <role>; it is never a file. It carries the request, the ticket acceptance criteria when present, the grounding pointers (never file bodies), the clarity label, the Project voice and your token budget.
Procedure
- Print your brief with
paqad-ai spec pipeline experts brief <role>. Read your lens, the file named for your role in the lens list under Resources. The lens is the only file you need: kinds, severities and the output shape are on this page, and each extra read costs budget. - Decide from the request and the grounding only. Do not read the whole repo.
- 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(requirementbecomes an FR or NFR,invariantan INV,acceptancean AC,riskan NFR or failure-path AC,non-goala Non-goals line) andseverity(must: the spec is wrong without it;should: strongly expected;could: safe to defer).references/finding-kinds.mdhas the longer version. Name every target in the project's words: see the Project voice section of your brief. - Phrase every question as a
PipelineQuestion({ business_text, why_it_matters, options, grounded_in }): business words, options phrased as outcomes, and the grounding reference it is grounded in (ornull). Ask only what the project's own docs cannot answer. - 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).
- 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. The verb stores each finding once in the change'sexperts.jsonand your tokens on your roster entry; never write that file yourself.
Output Contract
- One JSON object, shaped like
assets/output.template.md:{ "notes": [ { "role", "findings": [ { "target", "claim", "kind", "severity", "evidence"? } ], "questions": [ PipelineQuestion ] } ], "tokens": { "<role>": n } }. findingsandquestionsmay be empty. One note per brief; as a High Table seat that is one note, for your role.evidenceis an optional grounding reference.- The
qa-engineernote also carries"verdicts": { "spec_compliance": { "status", "reason" }, "quality": { "status", "reason" } }, each statuspass | concerns | fail: one verdict on whether the spec meets the request, one on whether it is testable and complete. No other role carries verdicts. paqad-ai spec pipeline experts notesvalidates it and assigns the idsEX-<role>-<n>in note order. Write the artifact outside the feature bundle (for example under.paqad/tmp/).
Escalate / Stop Conditions
- Never write as a role you were not given, and never add a "general" finding with no concrete target.
- Never write a question in mechanism words when a business phrasing exists: the plain-language check refuses it and names the flagged terms.
- Never exceed the granted budget in the brief; stop and report the tokens you used.
Resources
references/finding-kinds.md: the finding shape and what eachkindbecomes in the spec.assets/output.template.md: the canonical output shape.scripts/lint-output.sh: validates the output shape before you hand it back.runtime/base/skills/expert-notes/agents/openai.yaml: agent interface metadata.src/spec-pipeline/experts/notes.ts: the deterministic guard that validates this output.
Lenses, one per pickable expert; read only the one named by role:
references/lenses/agent-orchestrator.mdreferences/lenses/application-architect.mdreferences/lenses/data-modeler.mdreferences/lenses/db-expert.mdreferences/lenses/devops-engineer.mdreferences/lenses/integration-architect.mdreferences/lenses/market-researcher.mdreferences/lenses/performance-analyst.mdreferences/lenses/product-owner.mdreferences/lenses/qa-engineer.mdreferences/lenses/security-auditor.mdreferences/lenses/skill-orchestrator.mdreferences/lenses/solution-architect.mdreferences/lenses/user-flow-writer.mdreferences/lenses/ux-ui-analyst.md
04 同仓库更多 Skills
sample-skill
Sample bundled skill fixture
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
understand-idea
Chat and Claude Code: Step 1 of the discover journey: clarifies the goal, who benefits, success and constraints into the idea block. Use when the journey directs it to step 1, not directly.
size-work
Chat and Claude Code: Suggest a size for a ticket from comparable finished work, as a labelled suggestion the team still owns. Use it when someone asks "how big is this?", "roughly how much work is ABC-12?", or wants a backlog item sized. It finds the team's sizing scale at first use, picks two to five of the closest finished tickets with links, and gives a size or range with the drivers behind it and a confidence of low, medium or high, lowered and explained when the area's documents are template text. Every result is labelled a suggested size, never a date or a commitment. It writes nothing into the size field unless the user says "set it", and it refuses to overwrite an existing size unless the user asks to replace it. Produces the sizing block of the record.
refine-ticket
Chat and Claude Code: Improve one or more existing tracker tickets without losing the author's intent. Use it when someone wants a ticket read, diagnosed and tidied up ("this ticket is vague", "fix up ABC-12", "split this, it's too big"). It reads each ticket in full and snapshots it with its last-updated time, says what is wrong with evidence, and proposes a field-by-field before and after change set limited to summary, description, labels, parent, links and new child tickets on a split. It writes nothing until an explicit "apply it" bound to that exact change set, re-checks the ticket for conflicting edits just before writing, never replaces rich descriptions with plain text, never deletes or closes a ticket, and reads each ticket back after applying. Produces the existing and changes blocks of the record.