docs: audit and update CLAUDE.md for accuracy by chenders · Pull Request #28 · chenders/debriefer

chenders · 2026-03-21T03:35:24Z

Summary

Fix stale documentation that drifted after the @debriefer/ai and @debriefer/browser package extractions
Add architecture sections and dependency profiles for both new packages
Remove the all-Complete Implementation Status table (zero signal)
Fix CI description to match actual workflow structure
Add a "Maintaining This File" section with explicit update triggers so CLAUDE.md stays in sync going forward
Strengthen /do-commit command with specific CLAUDE.md update checklist

Test plan

npx prettier --check . passes (docs-only change)
CLAUDE.md architecture tables match actual package exports
Dependencies Policy matches actual package.json files

🤖 Generated with Claude Code

Copilot

Pull request overview

Docs refresh to bring repository documentation back in sync with the current monorepo architecture (notably the @debriefer/ai and @debriefer/browser extractions) and to split large README content into focused docs pages.

Changes:

Restructures README.md, adds a CLI “hook” example, and links out to new docs pages.
Adds new documentation pages for reliability tiers/source categories and integration examples.
Updates CLAUDE.md + .claude/commands/do-commit.md with new package architecture and “keep this file in sync” guidance.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
README.md	Reworks the main project landing page; adds a CLI run example and new navigation to docs.
docs/sources.md	Introduces reliability tier table + source category overview and threshold explanation.
docs/examples.md	Moves long integration examples out of README into a dedicated doc.
CLAUDE.md	Updates monorepo structure, architecture tables, dependencies policy, CI notes, and maintenance triggers.
.claude/commands/do-commit.md	Strengthens commit checklist with explicit CLAUDE.md update triggers.

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Restructure README from 514 lines to ~160, following a hook-first pattern: show CLI output demonstrating multi-source research before any code. Move integration examples to docs/examples.md and reliability scoring tables to docs/sources.md. Add @debriefer/ai and @debriefer/browser to packages table. Replace 70-line deployment section with a 5-row table linking to package READMEs. Add "Interesting Implementation Details" and "Project History" sections. Remove stale specific numbers from README and CLAUDE.md. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Fix ClaudeSynthesizer imports: moved from @debriefer/core to @debriefer/ai across all three examples in docs/examples.md - Fix docs/sources.md code snippet to use correct constructor signature (SourcePhaseGroup[] + synthesizer) and update prose from "two thresholds" to accurate description - Fix README hook description to match the command categories shown Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Label CLI output example as illustrative (not real CLI output) - Add @debriefer/ai and @debriefer/browser to CLAUDE.md monorepo tree Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add Brave to SEARCH_AGGREGATOR tier examples - Remove unused ScoredFinding import from RAG example - Fix browser fallback description (package is optional, not Playwright) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Remove specific counts from illustrative CLI output - Add imports to docs/sources.md code snippet for self-containment Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fix stale documentation that drifted after the ai/browser package extraction: - Core module table: ClaudeSynthesizer → NoopSynthesizer (moved to ai) - Add architecture sections for @debriefer/ai and @debriefer/browser - Fix Dependencies Policy: remove @anthropic-ai/sdk from core, add ai and browser package dep profiles - Fix CI description: 5 CI jobs + 2 Security workflow jobs, not "six" - Remove all-Complete Implementation Status table (zero signal) - Update Package Publishing guidance for leaf-package SDK pattern - Add "Maintaining This File" section with explicit update triggers - Strengthen /do-commit with specific CLAUDE.md update checklist Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- README: rewrite CLI example to match actual formatter output (Free/Paid phases, text format with Subject/Sources/Cost/Duration header) - README: use only keyless sources in example, note API key sources separately - CLAUDE.md: fix CI description — CodeQL is in ci.yml (push-only), security.yml only runs npm audit - CLAUDE.md: replace absolute deadonfilm path with GitHub URL Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Update flatted 3.4.1 → 3.4.2 to fix prototype pollution via parse() (GHSA-rf6f-7fwh-wjgh). Transitive dep via eslint → file-entry-cache → flat-cache → flatted. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- README: fix tier names in CLI example to match actual enum values (structured_data, secondary, tier_1_news — not uppercase member names) - docs/examples.md: add note about API key requirements for sources Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

Remove "with early stopping" from README CLI example description — the CLI doesn't set earlyStopThreshold (defaults to Infinity), so early stopping won't trigger in a default run. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

- CLAUDE.md: rename FallbackChain → fetchPageWithFallbacks to match actual export from archives/fallback-chain.ts - CLAUDE.md: rename AIClient → HaikuClient / AIClient to clarify the provider interface vs default implementation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Copilot · 2026-03-21T06:10:37Z

 ## The Hook

-What does a research run actually look like? Here's an illustrative example of the CLI researching Audrey Hepburn across structured data, news, and archives:
+What does a research run actually look like? Here's the CLI researching Audrey Hepburn across structured data and news sources (all free, no API keys needed):


The parenthetical “all free, no API keys needed” is misleading for --categories structured,news: the CLI registry includes guardian and nytimes, both of which require API keys and are skipped when unavailable (see packages/cli/src/source-registry.ts and packages/sources/src/news/{guardian,nytimes}.ts). Consider rephrasing to clarify that the run is keyless because unavailable key-required sources are filtered out via isAvailable() (and/or mention which sources are skipped without keys).

Copilot · 2026-03-21T06:10:38Z

+Sources: 18/20  Cost: $0.0000  Duration: 3.1s
+Stopped at phase 1
+


This sample output includes Sources: 18/20 and Stopped at phase 1, which won’t match the current CLI/core behavior for this command:

debrief.ts filters to availableSources before running, so attempted source counts will reflect available sources only (structured+news is 24 total, typically 22 available without Guardian/NYT keys).

stoppedAtPhase is only set when early-stop triggers (default earlyStopThreshold is Infinity) or the per-subject cost limit is reached; with free sources and the default budget ($1.00), Stopped at phase ... won’t be printed.
Recommend either capturing real output from a current run, or removing these drift-prone lines (counts / stoppedAtPhase) from the README example.

Copilot AI review requested due to automatic review settings March 21, 2026 03:35

Copilot started reviewing on behalf of chenders March 21, 2026 03:36 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

Comment thread README.md Outdated

Comment thread README.md Outdated

Comment thread CLAUDE.md Outdated

Comment thread CLAUDE.md Outdated

chenders requested a review from Copilot March 21, 2026 05:16

Copilot started reviewing on behalf of chenders March 21, 2026 05:16 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

Comment thread README.md

Comment thread docs/examples.md

chenders and others added 7 commits March 20, 2026 22:28

docs: address Copilot round 2 feedback

638450a

- Label CLI output example as illustrative (not real CLI output) - Add @debriefer/ai and @debriefer/browser to CLAUDE.md monorepo tree Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: address Copilot round 3 feedback

74be709

- Add Brave to SEARCH_AGGREGATOR tier examples - Remove unused ScoredFinding import from RAG example - Fix browser fallback description (package is optional, not Playwright) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: address Copilot round 4 feedback

3c5f17b

- Remove specific counts from illustrative CLI output - Add imports to docs/sources.md code snippet for self-containment Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chenders force-pushed the docs/claude-md-audit branch from 153bf13 to 995ba5f Compare March 21, 2026 05:30

chenders and others added 2 commits March 20, 2026 22:38

chore: fix high-severity flatted vulnerability

c6c170d

Update flatted 3.4.1 → 3.4.2 to fix prototype pollution via parse() (GHSA-rf6f-7fwh-wjgh). Transitive dep via eslint → file-entry-cache → flat-cache → flatted. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chenders requested a review from Copilot March 21, 2026 05:41

Copilot started reviewing on behalf of chenders March 21, 2026 05:42 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

Comment thread README.md Outdated

chenders requested a review from Copilot March 21, 2026 05:48

Copilot started reviewing on behalf of chenders March 21, 2026 05:49 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

Comment thread CLAUDE.md Outdated

Comment thread CLAUDE.md Outdated

chenders requested a review from Copilot March 21, 2026 05:54

Copilot started reviewing on behalf of chenders March 21, 2026 05:54 View session

chenders merged commit ea61da8 into main Mar 21, 2026
9 checks passed

Copilot AI reviewed Mar 21, 2026

View reviewed changes

Comment thread README.md

Comment thread CLAUDE.md

Comment thread CLAUDE.md

chenders requested a review from Copilot March 21, 2026 06:02

Copilot started reviewing on behalf of chenders March 21, 2026 06:02 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

		Sources: 18/20 Cost: $0.0000 Duration: 3.1s
		Stopped at phase 1

Conversation

chenders commented Mar 21, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants