Collapse near-duplicate lessons at briefing time so a pair does not take two slots

Open
  • Is something wrong?
#237 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
38/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend, testing

Research direction

Start by reading core.find_duplicates and duplicate_score, then trace how okl check fetches, ranks, and trims lessons, including the --format agent --interests path used by the harness. First complete prerequisite #177 step 1 so duplicate detection is symmetric. Done means the briefing names the lower-ranked duplicate, fills the freed slot with the next distinct lesson, leaves okl dedup unchanged, and passes the registered harness run.

Written by the indexing model from the issue text.

Description

enhancement

Problem

okl dedup reports near-duplicate pairs, and by design never merges them. The report is advisory, and nothing reads it at briefing time. When both members of a pair match a task they both take a slot, and a distinct lesson further down the ranking is the one trimmed at twelve.

Where it stands (verified 2026-10-20)

  • core.find_duplicates / duplicate_score back okl dedup ("never auto-merges") and the seed-time advisory; nothing else calls them.
  • okl check fetches three times the limit, filters scope and interests, and cuts at twelve. Two near-duplicates that both survive the cut are briefed in full, one after the other.
  • The score is asymmetric today (#177): three seed pairs cross the threshold in one argument order only. A collapse keyed on "pair above the threshold" would inherit that.

Proposal

At briefing time, when two hits form a dedup pair above the threshold, keep the higher-ranked one and name the other by id on its line (also [id2]), so the slot goes to the next distinct lesson. Nothing is merged, edited or hidden from okl show; the report stays as it is.

Prerequisite: #177 step 1, a symmetric score, so the pair is the same pair whichever lesson ranked first.

Measurement

This changes which lessons a single briefing contains, so it goes through the harness as a pre-registered run before it ships, after the deterministic pre-check that the change alters the harness's briefings (the harness shells out to okl check --format agent --interests, so the collapse must be on in that path and stamped in the receipt).

Acceptance

  • A planted near-duplicate pair: one appears, naming the other; the twelfth slot holds a lesson that was thirteenth before. Fails before the change.
  • okl dedup's report is unchanged.

Related: #177 (symmetric score), #25 (two lessons that disagree, which is a different pair), #94 (not re-briefing within a session is tracked there, behind its multi-turn reservation).

Dominant language
Python
Stars
1
Forks
1
Avg merge
5h 10m
Merged PRs (30d)
127

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from emeraldleaf/okl

All issues in emeraldleaf/okl

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.