fix(onboarding): resolve section count contradiction with skip rule#421
Conversation
PR #413 added Section 2 (How It's Used) with a skip rule for pure infrastructure repos, but left "exactly six sections" language and stale "five sections" references that contradicted the skip instruction. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e3d65b708f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Read files in parallel batches where there are no dependencies between them. For example, batch README.md, entry points, and AGENTS.md/CLAUDE.md together in a single turn since none depend on each other's content. | ||
|
|
||
| Only read files whose content is needed to write the five sections with concrete, specific detail. The inventory already provides structure, languages, frameworks, scripts, and entry point paths -- don't re-read files just to confirm what the inventory already says. Different repos need different amounts of reading; a small CLI tool might need 4 files, a complex monorepo might need 20. Let the sections drive what you read, not an arbitrary count. | ||
| Only read files whose content is needed to write the six sections with concrete, specific detail. The inventory already provides structure, languages, frameworks, scripts, and entry point paths -- don't re-read files just to confirm what the inventory already says. Different repos need different amounts of reading; a small CLI tool might need 4 files, a complex monorepo might need 20. Let the sections drive what you read, not an arbitrary count. |
There was a problem hiding this comment.
Make file-reading scope match the optional section skip
This update now requires reading content for “the six sections,” but Section 2 is explicitly skippable for pure infrastructure repositories, so the instruction can still push the agent to gather (or invent) consumer-facing material that should be omitted in that mode. Making this line count-agnostic (e.g., “the sections you will produce”) would keep Phase 2 aligned with the skip rule and avoid contradictory guidance during onboarding generation.
Useful? React with 👍 / 👎.
PR #413 added Section 2 ("How It's Used") with a skip rule for pure infrastructure repos, but left contradictory section-count language that could cause the agent to either produce an invalid 5-section doc or hallucinate a fake consumer view to satisfy the count.
Addresses this review comment.
Changes
🤖 Generated with Claude Opus 4.6 (1M context, extended thinking) via Claude Code