# 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

```markdown
# 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.