learningcircuit--local-deep-research/docs/strategies/deleted

Deleted advanced-search-system components — notes archive

This directory captures the novelty of components deleted from src/local_deep_research/advanced_search_system/ — strategies, question generators, constraint checkers, filters, candidate explorers, evidence gatherers. Git already stores the code and its history; the job of these notes is the prose explanation of what was novel and why, something git blame can't reconstruct.

Keep files short. Link to the deletion PR or commit for the code; write 1-2 sentences per idea, not verbatim copies.

(The directory is named docs/strategies/deleted/ for historical reasons — the hook started narrower. It now covers the whole advanced_search_system/ module.)

When to add a file here

Whenever a PR deletes one or more .py files anywhere under src/local_deep_research/advanced_search_system/. The require-strategy-deletion-docs pre-commit hook enforces this — a commit that deletes such a file without adding or updating a .md file in this directory will be blocked.

Exempt: __init__.py aggregators anywhere in the tree — deleting one by itself does not remove a component. Everything else, including base_strategy.py / base_question.py / other base_*.py, requires a notes file because deleting a base class is a significant refactor.

Naming

One file per deletion PR:

pr-<number>-<short-slug>.md

Examples: pr-3147-dead-strategies.md, pr-3205-entity-aware.md.

If a single PR deletes multiple components, document all of them in one file with one ## Component: section per deletion.

Template

# PR #<n> — <title>

Strategies/components deleted in PR #<n> (see that PR for the full
pre-deletion code — this file only summarises what was novel).

## Component: `<ClassName>`

- File deleted: `<path>` (<N> LOC at deletion).
- Reachability: <one line, e.g. "not in `search_system_factory.py`; only referenced by its own test">.
- Closest reachable successor: `<SuccessorClassName>` (`<path>`, factory key `"<X>"`).

### Useful ideas from the pre-deletion version

- **<short name>** — <1–2 sentences describing what it did and why
  it was distinctive, and whether it was validated>.
- **<short name>** — <...>.

### Why deletion was safe

<2–3 sentences mapping distinctive features to the successor, or
flagging at-risk items and why losing them is acceptable.>

### Recovery path

<1–2 sentences: prefer "add a flag on the existing class" over
"restore the deleted file". Or: "do not restore".>

The guiding principle — reference, don't duplicate

Write the notes as commentary on the code in git, not as a mirror of it. Example of the shape to aim for:

generate_creative_search_angles asked the LLM for 30–40 alternate-angle queries using a detective framing (character / title / genre guessing, reverse searches). Exploratory and never validated against a benchmark. Not replicated in ModularStrategy.

One paragraph conveys the idea. A reader who wants the exact prompt can follow the PR link or run git show <sha>:<path>. We are not re-hosting the code.

What a good bullet mentions

Each novelty bullet should be brief and answer:

• What the component did that was different from the successor.
• Why that difference was interesting (a heuristic, a tuning choice, a prompt-engineering trick, an interface gap it filled).
• Whether it was validated or exploratory — set expectations for anyone considering a revival.

Bullets worth writing are the ones a future reader can't easily infer by diffing the deleted file against its successor.

What not to include

• Verbatim copies of prompts, docstrings, or code blocks — the deletion PR already has them; don't re-host.
• Line-by-line diffs against the successor — the PR diff covers it.
• Discussion of review decisions — those belong on the PR itself.
• Apologies or extended rationale — the "Why deletion was safe" section should be 2–3 sentences, not an essay.