Spec Pov

Form a Point of View

Return a decisive, graded verdict on something from the outside world — judged against this project, not in the abstract.

Use the user's current request from the conversation as the POV input.

Note: Use the current date from the active host context. Use this when weighting external sources and dating artifacts.

The one rule that is the whole moat

Do not issue a verdict you did not earn against the project's own context. Generic web research already covers "tell me about X"; the differentiator is never "research the web" — it is the refusal to answer in the abstract. The verdict must clear two absolute floors (see references/method.md): a project floor (a concrete verified project fact — a named incumbent + a touchpoint, or for a net-new adoption the verified absence of one plus where it would fit, or a prior decision) and an external floor (at least one verified external source). The floors are absolute and independent — strong external evidence never compensates for a thin project leg, and vice versa. Neither the conversation nor the user's own assertions substitute for grounding.

Interaction Method

When you must ask the user a question, use the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex. Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. Ask one question at a time.

Model Tiers

Dispatch is tiered by task shape, never hardcoded to a model name:

• Extraction tier — the project-grounding scout and the precedent-&-activity scout: search-and-quote work. Request the cheapest capable tier only when worker_model_override: supported; otherwise inherit.
• Generation tier — the external-evidence researcher: web/docs retrieval and entailment checking. Request the balanced mid-tier only when worker_model_override: supported; otherwise inherit.
• Ceiling tier — the verdict reasoning itself (the two-floor gate, the skeptic synthesis, the verdict contract). This runs in the main conversation on the orchestrator's model; nothing is dispatched for it.

Dispatch Authorization Boundary

在派发 repo profiler、project/precedent scout 或 external researcher 前，记录：

worker_dispatch_authorization: authorized | missing
capability_probe: not_applicable | attempted | unavailable
worker_dispatch_capability: available | missing | unknown
worker_context_isolation: isolated | inherited | unknown
worker_model_override: supported | unsupported | unknown
worker_bounded_parallelism: supported | unsupported | unknown

workflow invocation does not authorize dispatch。POV tier、外部链接、tool availability、权限设置或需要满足 two floors 都不构成派发授权。只有当前用户或可见 upstream handoff 明确请求 subagent、delegated work、persona 或 parallel work 时才可派发。缺授权时不得探测 tool schema，固定为 capability_probe: not_applicable + worker_dispatch_capability: unknown，采用 bounded inline 或 serial grounding 并记录 dispatch_authorization_missing。只有授权后才把 current-session registry/schema 作为 provider_untrusted evidence 检查：确认缺失时记录 subagent_capability_missing；surface 不可用、schema 不完整或候选不唯一时记录 worker_capability_unproven，均使用同一 fallback。隔离、模型覆盖和有界并发只取 live facts；required isolation 未满足时保持依赖 gate 打开，model unknown 时继承，parallelism unknown 时串行。记录 worker_dispatch_outcome。The inline path must not claim independent scout coverage、fresh-context skepticism 或 multi-agent evidence；它只能声明 orchestrator 自身完成了有界的多 lens 核验。

Degradation rule. When authorized dispatch exists but worker_model_override is unsupported or unknown, dispatch scouts on the inherited model and keep their read budgets. When dispatch capability is missing or unknown, use the bounded inline fallback with the same evidence budgets and the claim limitation above.

Execution Flow

Phase 0: Frame and Classify

Output mode: by default spec-pov writes no document — the verdict is a compact chat block. An optional full write-up and a durable spec-compound capture are available on request at Phase 4. Do not resolve an OUTPUT_FORMAT or load a rendering reference up front.

1. Detect the invocation context — cold or warm. Warm means spec-pov was invoked mid-session for a second opinion, with the question sitting in the surrounding conversation or absent. For the warm contract beyond the frame — taking only the question and claims-to-verify (never grounding), the guest output, the provenance buckets — read references/invocation.md.

2. Establish the frame before grounding — orient, then infer or propose; never guess. The same input supports very different verdicts: a bare link to a new sign-in method could mean adopt it, migrate to it, compare it to what we have, or just answer a question about it. Guessing sends the scouts after the wrong question. So orient cheaply on what was provided — fetch a bare link lightly to learn what it is, recognize a bare topic, read a paste (orientation, not grounding) — then settle the subject and the POV intent (adopt / migrate / compare / is-this-our-problem / explainer):

   • Both clear → state the frame in one line and proceed.
   • Intent ambiguous (a bare link or topic with no stated intent, or a warm invocation with no clear question) → read references/intake.md and follow it: propose the concrete candidate framings this input suggests and confirm before grounding. Do not guess and fan out.

3. Apply the selection escape hatch. If the input is a selection over a field ("what should we use for auth?"), it belongs here only when the realistic field is bounded (roughly five or fewer real candidates) and the criteria are knowable. If the field can't be bounded without inventing options, or the criteria are unclear, stop: return a Hold and route to spec-ideate (to enumerate) or spec-brainstorm (to surface criteria), then offer to re-run. A product-design question the user owns is not a verdict. "How should I design this feature?" (form placement, page structure, UX shape) has no named external candidate to judge — deciding it inside spec-pov makes the product decision for the user in the wrong workflow. Route to spec-brainstorm (WHAT unsettled) or spec-plan (HOW planning), and do not return a verdict on it. Read references/boundaries.md only when the input's fit for spec-pov is genuinely in doubt or the field can't be bounded; skip it for a clearly in-scope verdict.

   Freeze an explicit approach set before grounding: every user-supplied candidate, the status quo when relevant, and the option to reject the framing or all candidates. Preserve this set through grounding, any peer cross-check, and the final verdict. Every approach must finish as recommended, rejected with a reason, deferred for missing evidence, or framing-rejected; narrative omission is not a disposition.

4. Classify the reversibility tier — three levels. Infer it from project signals:

   • Tier 1 — two-way door: a dependency, lint rule, or config; trivially reversible.
   • Tier 2 — one-way but bounded: a data store, an internal API/contract, or a migration whose blast radius stays inside this codebase.
   • Tier 3 — one-way and high-stakes: a security, legal, or privacy surface; a public API/contract; or an irreversible data migration.

   State the tier in the verdict and let the user override. The tier sizes the rest of the run (Phase 1 scout count, Phase 2 depth, Phase 3 reversal trigger): Tier 1 stays a one-screen verdict off a single combined grounding pass; Tier 2 adds the full scout fleet and an alternatives pass; Tier 3 adds deep external research, a precedent search, and a durable-record offer. Do not run a Tier-3 workup on a trivially reversible npm i, or hand a security-surface decision the moderate Tier-2 treatment.

Phase 1: Ground with authorized scouts or bounded inline fallback

Grounding searches code, git, the issue tracker, PRs, and docs. When the package-local boundary permits dispatch, use scout sub-agents that return only a dossier path plus a short gist. Otherwise apply the same persona budgets serially in the orchestrator, keep raw search notes in the scratch directory, and carry only compact evidence into verdict reasoning.

Resolve current project orientation first. Derive stack, dependency/license surface, conventions, and structure from the current target repo/worktree for this run. Record current git identity and dirty state when available, carry direct source refs, and never persist or reuse the orientation across runs, branches, or worktrees. If git or a required source cannot be read, record the concrete degraded fact and narrow the project-floor claim; do not substitute conversation claims or stale orientation.

Create the scratch dir once, and reuse the echoed path for every scout this run:

umask 077
SCRATCH_DIR="$(mktemp -d "${TMPDIR:-/tmp}/spec-first-pov.XXXXXX")"
[ -d "$SCRATCH_DIR" ] && [ ! -L "$SCRATCH_DIR" ] || { echo 'private scratch creation failed' >&2; exit 1; }
chmod 700 "$SCRATCH_DIR"
echo "$SCRATCH_DIR"

This directory is owner-only, ephemeral scratch. Recheck that it remains a non-symlink directory before atomic publication; durable POV evidence must use its canonical artifact owner rather than this path.

Every scout payload carries the same context. A fresh subagent does not inherit this conversation, so fill the persona files' {subject} / {scratch-dir} placeholders at dispatch: pass each scout the framed question (subject + intent), the named incumbent and the reversibility tier, and the resolved <scratch-dir> path — plus any user-supplied links for the external researcher. A scout seeded with only its generic persona grounds "some external thing" and can produce an empty or unfocused dossier.

Tier-sensitive execution. For Tier 1 (reversible), run a combined project-grounding and external-evidence pass at tight budgets; use subagents only when authorized, otherwise run the two lenses serially inline. Skip the standalone precedent lens because the project-grounding pass includes the prior-decision scan. For Tier 2/3, use the full fleet when authorized or the same three lenses serially inline:

• project-grounding scout (extraction tier) — read references/agents/project-grounding-scout.md and seed a generic subagent with it. With the agnostic profile already loaded from the cache, this scout runs only the candidate-specific slice: the named incumbent for this candidate, its call-sites/footprint, incumbent-pain, and the license/compat check against the profile's dependency-license set. Do not re-derive stack, conventions, or structure — those are in the profile. But note the profile may name an incumbent dependency, and a named dep is only a lead — it does not satisfy the project floor (see references/method.md), which still requires a freshly verified call-site the cache never holds. Do not let a cache-named incumbent short-circuit the fresh touchpoint check.
• precedent-&-activity scout (extraction tier) — read references/agents/precedent-activity-scout.md and seed a generic subagent with it. Always run its local-doc precedent pass (docs/solutions/, ADRs, design docs — file reads, no tools needed); only its tracker/PR portion is capability-gated and degrades gracefully when those interfaces aren't reachable. Do not skip the whole scout for missing tracker access — that would drop the only path that surfaces a prior local adopt/reject decision.
• external-evidence researcher (generation tier) — read references/agents/external-evidence-researcher.md and seed a generic subagent with it; capability-gated on web tools. Scale the remit to the tier so Tier 3's deeper-workup promise is real, not nominal: at Tier 3, seed it with a deeper brief — a wider source net, a larger read budget, and mandatory two-source corroboration on every load-bearing claim (at Tier 3 a single-source claim cannot anchor the verdict); Tier 2 uses the persona's standard budget and its prefer-two-sources default.

Capability gating is two-level: skip only a scout (or scout-portion) with no reachable surface at all — the project-grounding scout and the precedent scout's local-doc pass are file reads and always run; the tracker/PR reads and the external researcher are tool-gated and degrade. Let a scout that loses a tool mid-run self-report "unavailable." Never block on a missing surface — record it and let it lower the verdict's stated confidence, or trip the external floor (Phase 2) when the external leg is entirely absent.

Populate the provenance buckets from the returned dossiers, keeping them separate for Phase 2: observed-project-facts and verified-external-facts (these count as grounding) vs. conversation-claims and unconfirmed-assumptions from a warm invocation (these do not count until a scout corroborates them). Read dossiers from their paths on demand; do not pull their bulk into this context.

Phase 2: Verify against the two floors

Read references/method.md now, before reasoning about the verdict — it defines the Verify and Verdict steps, the skeptic stance and reversibility tiering as cross-cutting properties, and the two-floor Invalid-Verdict gate. Apply that gate as a pass/fail checklist over the dossiers: a failed floor forbids Adopt/Reject and returns the matching Hold subtype. Do this reasoning on the clean context — read a dossier on demand, never pull its bulk in.

Phase 3: Verdict

When the user or visible upstream handoff explicitly authorized cross-model/delegated work, read references/cross-model-panel.md before final synthesis. Apply its canonical authorization, external-data, allowlisted-input, redaction, source-identity, provider-independence, bounded lifecycle, and reap gates. Use references/agents/pov-peer.md, references/pov-schema.json, and the Skill-local adapter/runner only after every gate passes. Missing authorization or any safety fact means zero peer processes and no independent coverage claim. Reconcile valid peer disagreement against the two floors and the frozen approach set; never decide by vote.

Emit the verdict contract defined in references/method.md — grade vocabulary, schema fields, tier sizing, and output economy are all specified there. The verdict is a compact chat block, not a research report: lead with the grade, keep each schema field terse, and never reprint scout dossiers or raw search output. Size it to the tier — a Tier 1 verdict fits one screen; Tier 2/3 carries the full workup but still leads with the verdict and cites evidence rather than pasting it.

Phase 4: Follow-up

The chat verdict (the TL;DR) is the deliverable. What you offer next is reasoned from the verdict and sized to the tier — never a fixed menu, and never an assumption that everything routes to a plan.

Compute the next step. From the grade and the verdict's Handoff field, reason about the single best next move and a one-clause why — it is not always obvious between plan and brainstorm, so decide in context:

• Adopt, scope clear → take it into spec-plan.
• Adopt, scope still fuzzy → spec-brainstorm to pin down what "adopt" means before planning.
• Trial → scope a timeboxed spike (spec-work).
• Hold / Reject / Not-our-problem → no handoff; there is nothing to take forward.

Tier-gate the offer (anti-ritual):

• Tier 1, or a Reject / Not-our-problem grade → end with a single prose line — e.g. "Want the full write-up, or <computed next step>? Otherwise we're done." No blocking menu; silence means done.
• Tier 2/3 with an actionable grade → ask via the platform's blocking question tool, with the computed next step as the first, dynamically-labeled option:
  1. <computed next step> (e.g. "Plan the adoption with spec-plan") — seeded with the verdict substance, not a file pointer.
  2. Full write-up — the expanded, shareable artifact.
  3. Done. Add spec-compound as a one-line prose nudge under the menu, not a slot: "Want it in our decision history? say 'compound it.'" It is the least-frequent path and is never the first thing offered.

On each selection:

• Computed next step → invoke that skill via the platform's skill-invocation primitive, seeding it with the verdict substance (the decision, conditions, and verified facts).
• Full write-up → read references/report.md and follow it (HTML by default; opened locally via an available HTML tool). Opt-in; the default stays chat-only.
• "compound it" → invoke spec-compound with mode:headless, seeding it with the structured verdict for tooling_decision / architecture_pattern storage (no schema change; headless avoids its interactive prompts). Never mandatory.

Warm invocations stay a guest: output the verdict block, hand control back, and offer none of the above unless the user asks — a mid-session interjection does not push a next-step or capture decision.