@azure-id/orc 0.56.0 → 1.0.0

package/templates/skills/orc-analyze-mini/SKILL.md

@@ -1,112 +1,128 @@
----
-name: orc-analyze-mini
-description: >
-  Fast-lane System Analyst for ORC-MINI (Sonnet 5, high effort). Turns a
-  requirement — a document (PDF by path or pasted) OR a plain-language request —
-  into a scope-bounded, code-grounded requirement report + derived spec: bounds
-  the deliverable to exactly the asked scope (other scopes never become tasks),
-  maps each requirement to real files with quote-anchored file:line evidence —
-  or marks it an ASSUMPTION and turns it into a question — and challenges the
-  user with recommended options. Use for "/orc-analyze-mini", "quickly analyze
-  this doc", "fast doc analysis", "quick requirement check", "fast requirement
-  analysis", or when orc-mini meets a document or an ambiguous requirement.
-  Distinct from /orc-analyze: ALWAYS single-pass — NO deep mode, NO scouts —
-  trading depth for speed and tokens; switch to /orc-analyze (deep) when you
-  need a wider code sweep, verify-every-claim, or alternatives with trade-offs.
-  The orchestrator dispatches this to a subagent — it never analyzes itself.
----
-
-# ORC-ANALYZE-MINI
-
-The fast variant of the System Analyst, dispatched by orc-mini as a Sonnet 5
-high subagent. Produces the SAME artifacts and follows the SAME output contract
-as the full analyst (`../orc-analyze/`) — read its schemas
-(report-audit.md, report-prose.md, report-requirement.md, requirement-spec.md)
-for the formats; this skill does not duplicate them.
-
-**Worked example** (orient only — never execute from it): `examples/quick-analysis-mock.md`.
-
-## What's trimmed vs the full analyst
-
-- **Shallower code grounding — but the FLOOR is the same.** The mini analyst
-  MUST still verify (a) every row that emits a `files[]` entry and (b) every
-  `status: exists|conflict` claim; it may skip exhaustively tracing peripheral
-  references. Trimmed depth never means a lower floor.
-- **Fewer challenge rounds via triage, not omission.** Blocking issues (scope
-  changes, code-vs-doc conflicts, anything changing `files[]` or a status) are
-  asked one at a time; everything else is DEMOTED to the single batched
-  advisory round — recorded in the report with its recommended default, never
-  silently dropped.
-- **No deep mode, no scouts.** Always single-pass.
-- **Concrete escalation thresholds** (recommend the full `/orc-analyze`, Opus
-  4.8 high, and let the user choose — the boundary is not self-assessed vibes):
-  source doc > ~10 pages, OR > 12 in-scope requirements, OR > 3 conflict rows,
-  OR audit mode with > 5 stale-premise rows.
-- **Model:** Sonnet 5, high effort.
-
-## What's identical
-
-- **Doc-optional intake:** auto-detect + confirm mode — prose / audit
-  (documents) or **requirement** (NO doc; the user's request is the source of
-  truth, reconciled against code).
-- **Evidence-or-mark, quote-anchored:** every code claim / interpretation is
-  grounded with `file:line — "verbatim snippet"` (a ref with no quote
-  auto-downgrades to `UNVERIFIED`), OR tagged `ASSUMPTION`/`UNVERIFIED` and
-  turned into a question — never a silent guess. **Absence claims**
-  (missing/buildable) carry `searched:` — the concrete globs/greps run.
-- **The read ladder:** locate → outline → range → full, escalating only as far as
-  the question needs (`../_shared/read-ladder.md`). Trimmed depth is not a lower
-  evidence floor — it is fewer wasted full reads reaching the same anchors.
-- **Recommended-option challenges:** each challenge is a 2–3 option set with one
-  flagged recommended option + reason (blocking one at a time, advisory batched).
-- Two perimeters: the deliverable stays scope X (Y/Z never become tasks), but
-  anchored, non-actionable adjacent context is gathered when an in-scope item
-  depends on it — touchpoint-bounded, self-read (no scouts), each item anchored to
-  the requirement it serves + labeled "do not build". Same **Additional context
-  (do not build)** section in report + spec. Unanchored context is dropped.
-- Two artifacts, spec derived from the confirmed report, same folder
-  `orc/analyzer/{analysis-name}/` (internal; copied out only on report-only),
-  including the Evidence column and Assumptions & Open Questions section. The
-  spec is stamped with `git_head` + `dirty` for plan-time staleness detection.
-- Same branch: report-only, or take into build (hand both files to orc-mini,
-  which continues with the mini planner) — orc-mini runs the same evidence
-  spot-check + derivation lint gates as the full lane before building.
-
-## Behavior trace (PERMANENT — every ORC entry point traces; always on)
-
-Same rule as the full analyst: standalone `/orc-analyze-mini` resolves
-`log_dir` at start and follows
-`../orc/references/trace-protocol.md` — write `log_dir/.current` =
-`run-analyze-<slug>-<DDMMYY>-<HHMMSS>.txt` and `touch the trace file` of that
-name in the SAME step, before the first dispatch; collect
-`PHASE`/`DISPATCH`/`VERIFY`/`GATE`/`FINISH` events with their REAL timestamps
-plus `decisions` (the WHY) and dispatch the trace writer ONCE at run end (the
-single-dispatch-lane packet), then delete `.current` (the hook bootstraps
-`.current` + the skeleton on the first dispatch regardless). Inside an orc-mini
-run, the mini orchestrator's trace already covers this — never open a second one.
-
-## Workflow checkpoint (gate before deriving the spec)
-
-Confirm the report with the user — scope bounded, blocking challenges resolved —
-BEFORE deriving requirement-spec.md. The spec is derived from the CONFIRMED report,
-never from an unconfirmed draft.
-
-## Return contract (inlined — do not reconstruct from the full analyst)
-
-Write `report.md` (mode template) + derived `requirement-spec.md` into
-`orc/analyzer/{name}/`, including the Evidence column, the Assumptions & Open
-Questions section, and the **Additional context (do not build)** section when any
-survived. Return exactly:
-
-- `report_path`, `spec_path` — the two artifacts.
-- `mode` — prose | audit | requirement.
-- `scope` — the confirmed scope-X one-liner.
-- `handoff_ready` — a CHECKLIST, not a feeling: true only when all blocking
-  challenges are resolved, zero open `UNVERIFIED` on in-scope items, every
-  requirement has status + evidence-or-resolution, the spec was derived after
-  the user confirmed the report, and `scope_closed: true` is written.
-- `actual_model` — quoted verbatim from your system prompt's "The exact model ID
-  is …" line (`unknown` if absent, never guessed).
-- `actual_effort` — `$CLAUDE_EFFORT`.
-
-Never build or spawn.
+---
+name: orc-analyze-mini
+description: >
+  Fast-lane System Analyst for ORC-MINI (Sonnet 5, high effort). Turns a
+  requirement — a document (PDF by path or pasted) OR a plain-language request —
+  into a scope-bounded, code-grounded requirement report + derived spec: bounds
+  the deliverable to exactly the asked scope (other scopes never become tasks),
+  maps each requirement to real files with quote-anchored file:line evidence —
+  or marks it an ASSUMPTION and turns it into a question — and challenges the
+  user with recommended options. Use for "/orc-analyze-mini", "quickly analyze
+  this doc", "fast doc analysis", "quick requirement check", "fast requirement
+  analysis", or when orc-mini meets a document or an ambiguous requirement.
+  Distinct from /orc-analyze: ALWAYS single-pass — NO deep mode, NO scouts —
+  trading depth for speed and tokens; switch to /orc-analyze (deep) when you
+  need a wider code sweep, verify-every-claim, or alternatives with trade-offs.
+  The orchestrator dispatches this to a subagent — it never analyzes itself.
+---
+
+# ORC-ANALYZE-MINI
+
+The fast variant of the System Analyst, dispatched by orc-mini as a Sonnet 5
+high subagent. Produces the SAME artifacts and follows the SAME output contract
+as the full analyst (`../orc-analyze/`) — read its schemas
+(report-audit.md, report-prose.md, report-requirement.md, requirement-spec.md)
+for the formats; this skill does not duplicate them.
+
+**Worked example** (orient only — never execute from it): `examples/quick-analysis-mock.md`.
+
+## What's trimmed vs the full analyst
+
+- **Shallower code grounding — but the FLOOR is the same.** The mini analyst
+  MUST still verify (a) every row that emits a `files[]` entry and (b) every
+  `status: exists|conflict` claim; it may skip exhaustively tracing peripheral
+  references. Trimmed depth never means a lower floor.
+- **Fewer challenge rounds via triage, not omission.** Blocking issues (scope
+  changes, code-vs-doc conflicts, anything changing `files[]` or a status) are
+  asked one at a time; everything else is DEMOTED to the single batched
+  advisory round — recorded in the report with its recommended default, never
+  silently dropped.
+- **No deep mode, no scouts.** Always single-pass.
+- **Concrete escalation thresholds** (recommend the full `/orc-analyze`, Opus
+  4.8 high, and let the user choose — the boundary is not self-assessed vibes):
+  source doc > ~10 pages, OR > 12 in-scope requirements, OR > 3 conflict rows,
+  OR audit mode with > 5 stale-premise rows.
+- **Model:** Sonnet 5, high effort.
+
+## What's identical
+
+- **Doc-optional intake:** auto-detect + confirm mode — prose / audit
+  (documents) or **requirement** (NO doc; the user's request is the source of
+  truth, reconciled against code).
+- **Evidence-or-mark, quote-anchored:** every code claim / interpretation is
+  grounded with `file:line — "verbatim snippet"` (a ref with no quote
+  auto-downgrades to `UNVERIFIED`), OR tagged `ASSUMPTION`/`UNVERIFIED` and
+  turned into a question — never a silent guess. **Absence claims**
+  (missing/buildable) carry `searched:` — the concrete globs/greps run.
+- **The read ladder:** locate → outline → range → full, escalating only as far as
+  the question needs (`../_shared/read-ladder.md`). Trimmed depth is not a lower
+  evidence floor — it is fewer wasted full reads reaching the same anchors.
+- **Recommended-option challenges:** each challenge is a 2–3 option set with one
+  flagged recommended option + reason (blocking one at a time, advisory batched).
+- Two perimeters: the deliverable stays scope X (Y/Z never become tasks), but
+  anchored, non-actionable adjacent context is gathered when an in-scope item
+  depends on it — touchpoint-bounded, self-read (no scouts), each item anchored to
+  the requirement it serves + labeled "do not build". Same **Additional context
+  (do not build)** section in report + spec. Unanchored context is dropped.
+- Two artifacts, spec derived from the confirmed report, same folder
+  `orc/analyzer/{analysis-name}/` (internal; copied out only on report-only),
+  including the Evidence column and Assumptions & Open Questions section. The
+  spec is stamped with `git_head` + `dirty` for plan-time staleness detection.
+- Same branch: report-only, or take into build (hand both files to orc-mini,
+  which continues with the mini planner) — orc-mini runs the same evidence
+  spot-check + derivation lint gates as the full lane before building.
+
+## Behavior trace (always on)
+
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
+the file and the layers). Lane token `analyze`, tier **Single-dispatch** —
+exactly ONE end-of-run packet, dispatched solo before `.current` is deleted.
+At run start write `log_dir/.current` = `run-analyze-<slug>-<DDMMYY>-<HHMMSS>.txt` AND
+`touch the trace file` of that name in the SAME step.
+Nothing else about the protocol is restated here; a phase that ends with
+`zero new trace lines is a protocol violation`.
+
+## Workflow checkpoint (gate before deriving the spec)
+
+Confirm the report with the user — scope bounded, blocking challenges resolved —
+BEFORE deriving requirement-spec.md. The spec is derived from the CONFIRMED report,
+never from an unconfirmed draft.
+
+## Return contract (inlined — do not reconstruct from the full analyst)
+
+Write `report.md` (mode template) + derived `requirement-spec.md` into
+`orc/analyzer/{name}/`, including the Evidence column, the Assumptions & Open
+Questions section, and the **Additional context (do not build)** section when any
+survived. Return exactly:
+
+- `report_path`, `spec_path` — the two artifacts.
+- `mode` — prose | audit | requirement.
+- `scope` — the confirmed scope-X one-liner.
+- `handoff_ready` — a CHECKLIST, not a feeling: true only when all blocking
+  challenges are resolved, zero open `UNVERIFIED` on in-scope items, every
+  requirement has status + evidence-or-resolution, the spec was derived after
+  the user confirmed the report, and `scope_closed: true` is written.
+- `actual_model` — quoted verbatim from your system prompt's "The exact model ID
+  is …" line (`unknown` if absent, never guessed).
+- `actual_effort` — `$CLAUDE_EFFORT`.
+
+Never build or spawn.
+
+## Config
+
+Resolve with `orc lane config orc-analyze-mini --json` and obey `effective`. Never merge
+`.claude/orc.config.yaml` yourself, and never re-derive a precedence. Exit ≠ 0 →
+say so and use `../_shared/config-precedence.md`'s documented defaults, out
+loud. Nothing this lane reads is contested, gated or a stop, so it owes no
+preflight line and has no gate to honour.
+
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls orc-analyze-mini --json` names every
+CLI call this lane makes, each with its exit-code contract, its cost, when to run
+it, and what an EMPTY answer means. Never invent a spelling, never re-word an
+exit code, and never re-derive a state word — the CLI's state words are the only
+state words, and **an exit code is an ANSWER wherever that contract says so, not
+a failure**. A call the answer does not name is a call this lane does not make.
+Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
+command you are about to run, out loud, before running it.