joenandez/spectre/spectre-capture

capture

Purpose

Maintain concise, reusable project guidance proactively. Capture never gates delivery, verification, acceptance, or PR progression.

Inputs

• A consequential lasting decision/reversal, accepted correction, verified reusable pattern/gotcha/constraint, disproved guidance, or confirmed persistent-blocker transition.
• Current-request discovery and exact-loaded candidates, when available; host project directory, tag intent, and candidate ID/revision when updating.
• No workflow, feature, run, or PR association: this skill owns maintained knowledge, not work history.

Working Set

• Reuse discovered/loaded candidates that answer the same future question. Refine only an unresolved question; do not repeat a broad search at the capture boundary.
• Read references/tagging-policy.md and references/knowledge-capture-input.json. Search tags only to resolve missing aliases, omitted areas, or genuinely new tag intent; exact-load a record only when needed.
• Use relevant files already acquired for entry points. Focus-read to validate observed lines when needed; do not dump files or invent locations.

Outputs + DONE

• A typed capture result: saved, updated, superseded, retired, no-op, skipped, or surfaced failure, with ID, revision, and canonical recordPath when applicable.
• Knowledge content has four distinct responsibilities: applicability (useWhen); current conclusion first, with why and practical consequences (content); selected code entry points; supporting evidence (evidence). Keep the summary a short routing aid rather than a repeat of the guidance. Aim for 250–600 rendered tokens as a soft editing target; split independent questions when useful, and retain required facts and gates over size.

DONE when: a supported durable fact is captured through the typed path, or a skip/no-op/failure is reported truthfully without changing workflow authority.

Method / guardrails

1. Capture facts that change a likely future decision, prevent a repeated failure, or route to relevant code. Routine progress, incidental code observations, transient command errors, and task completion alone do not qualify.
2. An explicit user statement that a lasting decision is current, corrected, or superseded is authoritative. Do not wait for repository corroboration or reconfirmation. When a correction is accepted, rewrite contradictory current guidance and its title, summary, and useWhen together; do not leave the old conclusion imperative. Use existing revision-aware updates, statuses, and relatedRecordIds to reconcile known competing guidance and preserve history. Surface write/conflict failures accurately; never claim unresolved records were reconciled or sweep the corpus.
3. Bound provider observations by observed version, date, and configuration; state when they need rechecking. Keep phase obligations, experiment settings, and one-session permissions separate from project-wide guidance. Explain genuinely unavailable or non-code entry points; a user correction remains valid even without a known code location.
4. Put entryPoints in the semantic input from relevant acquired files: each location has path, symbol or document section, observed positive line, and role. Use a specific explanation for actual unavailable/non-code portions; mixed known and unavailable locations may include both. No file dumps, invented lines, or boilerplate excuses.
5. Submit JSON on standard input: knowledge-cli.mjs capture --kind knowledge --input - --project-dir <project-dir> --json. New input needs tag intent; reuse a canonical area or create only under the shared policy. Use --input <path> only for explicit manual/advanced capture or returned recoveryInput.
6. An unchanged retry is a no-op. Changed records require the loaded revisionToken as --expected-revision; preserve omitted tags. Never edit canonical packages, index.json, or history.
7. A capture failure returns recovery input and remains non-blocking. It never becomes a workflow gate.

Handoff

Return the trigger or skip reason, tag and record outcome, ID/revision/conflict, canonical recordPath, applicability, evidence references, and recovery input when applicable.

Escalate-If

• Accepted directions conflict without a clear current decision, or applicability cannot be determined; surface the conflict without guessing.
• A write cannot recover through the available path; report recovery input without blocking delivery.