joenandez/spectre/spectre-work-record

work-record

Purpose

Truthful work history; workflow state/telemetry own live progress. Capture never changes delivery, verification or acceptance authority.

Inputs

• Exact run/work identity and applicable branch, PR or repository/base/head/diff association; observed lifecycle, account, entry points, tag intent and prior revision.
• Owned boundary: one Execute start/completion; meaningful blocked handoff/resolution when authority, control or context prevents safe continuation/resumption; Ship after PR creation; standalone Create PR terminal write only without an Execute/Ship owner; explicit snapshot/correction, including outside workflows.

Working Set

• Reuse applicable discoveries/loads; refine only unresolved questions. Read references/work-capture-input.json and ${CLAUDE_PLUGIN_ROOT}/skills/spectre-capture/references/tagging-policy.md.
• Use acquired entry points; focus-read as needed: path, symbol/document section, observed positive line, role. Explain unavailable/non-code portions, including uncreated start locations; never invent locations or dump files.

Outputs + DONE

Short title/routing summary and required identity/provenance/status metadata, derived reliably. Complementary fields:

• requestedOutcome: request; scope: boundaries.
• actualChanges: delivered behavior/artifacts; reasons: non-obvious rationale/trade-offs. Start/blocked accounts distinguish delivered from undelivered.
• discoveries: findings and maintained-authority links; relatedContext: typed entry points and bounded references.
• verification: observed checks; remainingWork: residual implementation. Structured verification and PR lifecycle remain authoritative.

State absence truthfully; omit filler, duplicated narrative/state. New/revised accounts stay under 2,000 estimated rendered tokens; reference evidence, not logs.

DONE: permitted boundary has a truthful account or surfaced skip/no-op/conflict/failure, with exact work ID, revision and canonical recordPath when applicable.

Method / guardrails

1. One record per exact Execute run: resume revises it; distinct runs never fold regardless of branch/feature/candidate. Branches/PRs may reference multiple records. Execute-owned writes include --source-run-id <exact-run> alongside other identity flags for receipt derivation.
2. Execute start requires exact identity/branch; every not-yet-true section says None yet., not placeholders (TODO, REPLACE_ME, angle brackets). Capture only the Inputs boundaries, never tasks, batches, checks, reviews, commits, ordinary decisions, routine progress, transient remediation or context refreshes.
3. New/current-run writes read git rev-parse --abbrev-ref HEAD, require explicit exact branch evidence, compare independent run-start evidence when available and preserve known same-run branch. Return recovery/skip if unavailable. Exact historical corrections may preserve unknown original branch by omitting --branch; never backfill from today's checkout. New historical snapshots require verified original branch.
4. Existing PR identity/URL requires gh pr view <identity-or-url> --json state outside store locks. Pass observed pullRequest; unavailable/unknown state, terminal-history contradiction or unqueryable draft without identity returns recovery/skip. Execution, verification and PR states stay separate:

• execution: unknown|in-progress|implementation-ready|acceptance-pending|blocked|finalized.
• verificationState: unknown|not-run|checked|passed|failed.
• pullRequest: unknown|none|draft-open|closed|merged; bare open is invalid.

1. Authorized terminal Execute uses execution.state: finalized, remainingWork: "None." exactly (otherwise CAPTURE_INPUT_INVALID). Blocked/failed/interrupted accounts stay non-final with scoped residual work; review, CI, PR readiness, merge and closure are not implementation work.
2. Fill semantic JSON outside the store; submit on stdin:

knowledge-cli.mjs capture --kind work --input - --project-dir <project-dir> --json. New/current-run writes add --branch <exact-branch> and exact identity via --work-id <id>, --source-run-id <run>, --pull-request-id <pr> or --candidate <exact-json>. Historical corrections require --work-id <id> --expected-revision <revision>. Changed records require loaded revisionToken as --expected-revision and preserve omitted tags; unchanged retries are no-ops. --input <path> is only for explicit manual/advanced capture or returned recoveryInput.

1. At owned terminal boundaries, promote only qualified reusable discoveries absent from maintained guidance via /spectre:spectre-capture, or link existing authority. No mandatory knowledge record per completion or added scan/write boundary. Capture failure/conflict returns recovery input without blocking delivery.

Handoff

Boundary, exact work ID, revision/conflict, canonical recordPath, associations, lifecycle facts and applicable recovery input.

Escalate-If

Unclear ownership/boundary, conflicting historical authority or unrecoverable write: surface recovery/skip without guessing or blocking delivery.