Prior Work Retrieval

Prior Work Retrieval

Run this before substantial production only when the trigger above is present. Read-only current-state checks stay direct unless the user asks for history. Its job is not to generate another summary. Its job is to answer: what already exists, which source is current, what should be reused, and what remains genuinely new?

Not for: current-file inspection, ordinary bug fixes, mechanical verification, or a task merely because the final answer happens to be a report/summary. A mention of current/现有 tests, README, files, implementation, behavior, or validation is not by itself a prior-work request. Do not infer the trigger merely because new work might duplicate something — that risk alone does not make a request explicit.

Completion contract

A retrieval pass is complete only when all five are true:

1. The task's real business outcome is written as one sentence.
2. Every relevant carrier declared in the manifest reports searched, manual_completed, or an explicit failure/coverage gap.
3. Candidate claims are opened at their original path or record, not accepted from a search snippet alone.
4. Each adopted item has a reuse or adapt decision and a reason tied to the current task. If nothing is adopted, the receipt carries a concrete no_reuse_reason.
5. scripts/prior_work.py check accepts the receipt for this session.

retrieved is not verified; verified is not reused. Keep those states separate so “I searched” cannot impersonate “I used our best prior work.”

Workflow

1. Read the local operating context first

Before querying, read the current project's AGENTS.md/CLAUDE.md, navigation index, and any North Star/current-decision file they name. Historical material cannot override a newer explicit decision.

2. Validate the explicit source manifest

The manifest is the only discovery scope. No directory exists merely because a convention says it should. Default path:

uv run --no-project python scripts/prior_work.py \
  --manifest <path> validate-manifest

The default is ~/.config/daymade/prior-work/sources.json; a project may pin another path. Global options precede the subcommand. The schema and carrier examples are in references/source-manifest.md.

3. Retrieve across declared carriers

Write the user-world outcome separately from the proposed implementation. Then provide two term sets:

• --outcome-term: 1–5 artifact/event/entity/date terms that could locate an already-finished result (accepted deliverable, canonical transcript, deployed service, decision, or operating evidence).
• --term: 1–8 implementation terms (code symbols, old workflow names, technical nouns, failure symptoms).

The runtime sends the business-outcome query to documents, meetings, archives, and conversations; it sends the implementation query to code and Skill carriers. Outcome candidates are ranked first. A code search can therefore no longer stand in for checking whether the requested result already exists. Do not pass generic verbs such as “做 / 优化 / 系统” alone.

uv run --no-project python scripts/prior_work.py retrieve \
  --business-outcome 'the observable result the user actually needs' \
  --outcome-term 'accepted artifact, entity, event, or date' \
  --query 'the implementation or workflow currently being considered' \
  --term 'distinctive entity' \
  --term 'old workflow name' \
  --term 'failure symptom' \
  --session-id "$CODEX_SESSION_ID"

Do NOT redirect the output (> /tmp/run.txt) to save it: by design (2026-08-27, regression-locked in test_unquoted_redirection_even_after_ route_stays_gated) a file redirection trips the write gate even on a read-only route command, so a redirected retrieve is blocked and the run JSON never lands where you aimed. Let the output print and read it from the transcript; the durable copy is the run JSON under the manifest's state_dir (its run_path is printed on the last line).

--session-id: use it only with retrieve, complete, and check; validate-manifest does not accept it. On Codex use $CODEX_SESSION_ID. Claude Code has no such env var, so take the exact id carried verbatim in prior-work hook messages (UserPromptSubmit inject / PreToolUse deny / Stop block). The receipt filename shown beside it is the id's sha256, not the id itself; completing a receipt under a guessed id writes a file check will never read and the gate keeps rejecting. Never substitute the hash-looking filename for the id.

When a normally optional live carrier is material to the request, promote it explicitly: --require-source live-wechat. The receipt cannot complete until that manual route is recorded.

The command searches filesystem carriers with rg, calls explicitly declared command adapters (for example the formal Claude-history finder), and surfaces manual routes such as live WeChat. Content search is always bounded by declared globs; full path enumeration runs only when an outcome/implementation term is explicitly path-shaped (a filename, path, or ISO date). A symbol such as project_doc_max_bytes does not justify walking every filename in a workspace. The command writes an immutable run JSON under the manifest's state_dir and returns its run_id.

If a required carrier says manual_required, perform that named Skill route and record its result before completion. A local WeChat archive search does not prove live WeChat coverage; a conversation index does not prove meeting or code coverage.

4. Verify candidates at authority

For a request to recover a deployed artifact, first bind the named system and the requested state (historical edition, used at a specific time, or current deployment). A related design document is a candidate, not the recovered file. Follow the project's artifact/deployment owner before selecting a similarly named experiment. If runtime proof is accessible, obtain it before delivering; an “unverified” disclaimer does not complete the lookup. If the user explicitly wants a historical draft, return that edition without imposing a live check.

Open promising candidates at their original path. Check:

• Match: does it solve the same business problem, not merely share words?
• Authority: current implementation/SSOT beats a historical proposal; raw transcript proves what was said, not that it remains correct.
• Freshness: compare current Git HEAD, file mtime, decision date, and any superseded marker. Do not use an archive to overwrite current behavior.
• Outcome evidence: prefer code/tests/accepted deliverables and operating results over a process that merely looks complete.

Dismissing a batch of hits is itself a claim. When a carrier returns many matches and you judge all of them irrelevant — "those are just the term being quoted in documentation", "that is an unrelated module" — that judgement is a finding you are about to report, not a filtering step you did on the way to one. Open at least one hit per distinct shape you are dismissing, and say in the receipt which shapes you ruled out and on what evidence. A carrier that returns 47 matches and contributes nothing to the answer is the same observation as a carrier that returns nothing, and it deserves the same scepticism as any other negative result: the run that produced it may be fine while your reading of it is not.

5. Complete the reuse receipt

When an archived request contains an actual file read, first use verify_artifact.py to compare the selected deliverable, not a nearby reference, against its correlated tool result:

uv run --no-project python scripts/verify_artifact.py \
  --candidate /tmp/agent-backup.zip --member skills/editor/SKILL.md \
  --archive /tmp/request.json.gz --read-path /agent/skills/editor/SKILL.md

The checker accepts JSON/gzip bundles with request_id, a timezone-qualified timestamp, and request.body.messages in Anthropic tool-call format. Omit --member for a plain file. Exit 0 means the candidate's bytes appeared in a successful correlated read at the recorded time — byte-exact for raw-byte readers (read/read_file), or, for Claude Code's Read, a line-numbered result whose absolute row numbers provably span the whole file and reconstruct it (a partial offset/limit read can never pass; the JSON's match_basis says which proof held, and rejected_read_reconstructions counts numbered reads that failed the coverage preconditions). 1 means no matching proof; 2 means invalid/ambiguous evidence. Path mentions, failed reads and related old files do not pass. Other evidence formats remain supported by the source-specific reader; do not convert an unsupported format into a negative claim.

The archive must come from the verified system's source-specific reader or observability tool. This check cannot authenticate an archive, decide which system the user meant, or establish current deployment. It also does not prove that every dependency was recovered. Preserve these distinctions in the handoff. For artifact retrieval, record the selected artifact/member and its matching evidence in the adoption reason. A receipt about a locator document alone does not establish that the final artifact is correct.

Classify the items you actually inspected:

uv run --no-project python scripts/prior_work.py complete \
  --run <run_id> \
  --reuse '<candidate_id>=reuse unchanged because ...' \
  --adapt '<candidate_id>=adapt boundary X because ...' \
  --session-id "$CODEX_SESSION_ID"

If none qualify, use --no-reuse-reason with the verified mismatch. “No hits” is not a reason; it is a retrieval observation and may require widening terms or resolving a failed carrier. A zero-candidate required carrier cannot be reported as "none exists" by paraphrase either. Check index provider coverage and freshness, refine indexed terms, and report the remaining gap. Do not run an unindexed whole-history label census.

Results at low confidence are not zero results. When a carrier reports result_count > 0 alongside terms_passed: false, expand those ranked results before writing the receipt. terms_passed: false says only that the query words did not appear in their literal form inside the top-K; it does not say the results are irrelevant, and under hybrid or BM25 ranking the leading hit is often exactly the synonym you were looking for. Write the receipt only after reading them.

That requirement is about what the receipt must be able to show. A no_reuse_reason has to point at named results and say why each one does not solve this task — "I read these three and they cover a different system" is a reason; "no record of the user discussing this" is not, when the carrier returned twelve hits nobody opened. Pair this with the zero-candidate clause above: that one governs a carrier that returned nothing, this one governs a carrier that returned something you have not yet earned the right to dismiss. Both directions have to close, or an unopened batch silently becomes an absence claim.

The completed receipt preserves business_outcome and outcome_terms; check rejects legacy or hand-built receipts that omit either field. Receipt freshness is bound to the definitions of required carriers. Editing an optional carrier does not invalidate already verified required coverage; changing a required root, route, mode, authority, or limit does. The full manifest hash remains provenance. Then verify:

uv run --no-project python scripts/prior_work.py check \
  --session-id "$CODEX_SESSION_ID"

Only after this passes should substantial production begin. Cite adopted candidate IDs in the implementation/plan so the receipt is connected to the result instead of becoming ceremonial paperwork.