Skip to content

fix(docs-review): check related docs by name and directory, not just identifier grep #3233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
csoceanu wants to merge 3 commits into from
Closed

fix(docs-review): check related docs by name and directory, not just identifier grep #3233

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ec0bf47
fix(docs-review): check related docs by name and directory, not just …
csoceanu Jul 7, 2026
a46bd70
fix(docs-review): exclude PR-modified docs from name/directory match
csoceanu Jul 7, 2026
8ac17f5
Merge branch 'main' into fix/docs-review-related-docs-check
csoceanu Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions internal/scaffold/fullsend-repo/skills/docs-review/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,12 +124,19 @@ From the script output, collect all matched doc files into a
candidate list. Exclude documentation files that are already modified
in the same PR — those are being actively updated.

Additionally, for each changed code file, check whether a
documentation file covering the same feature exists based on file
name and directory structure. If one exists and is not already in the
candidate list, add it.
Comment thread
qodo-code-review[bot] marked this conversation as resolved.
Outdated

@qodo-code-review qodo-code-review Bot Jul 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Informational

2. Related-doc match underspecified 🐞 Bug ⚙ Maintainability

The new “match by file name and directory structure” instruction doesn’t define a concrete heuristic
(what directories to search, what constitutes a match, or how many candidates to add), so different
runs/agents can apply different interpretations and produce inconsistent candidate sets. This
ambiguity is duplicated into the docs-currency sub-agent instructions, increasing variance in
behavior.
Agent Prompt 
## Issue description
The new related-doc discovery step relies on “file name and directory structure” but does not specify how to perform the mapping. Without a defined heuristic and limits, different agents may select different docs (or too many docs), reducing repeatability.

## Issue Context
This instruction is now present both in the docs-review skill (step 4) and in the docs-currency sub-agent summary, so it should be specific enough to apply consistently.

## Fix Focus Areas
- internal/scaffold/fullsend-repo/skills/docs-review/SKILL.md[127-130]
- internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/docs-currency.md[18-22]

Suggested change: document an explicit heuristic (and bounds), e.g.:
- Only consider docs under known doc roots (docs/, README*, etc.).
- Match by basename/stem (case-insensitive), optionally plus one parent directory segment.
- Cap added candidates per changed file (e.g., top 1–3 matches).
- Provide 1–2 examples of expected matches/non-matches.
This makes the step reproducible and reduces over-expansion of candidates.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


### 5. Evaluate every candidate (two passes)

**Pass 1 — Quick scan.** For each candidate doc file from step 4,
view only the lines that matched the grep (use `grep -n` to see them
in context). Based on the matching lines alone, decide whether the
doc might be stale. Record a verdict for every candidate:
in context). For candidates added by name/directory match without
grep hits, read the doc's section headings to determine if it
describes behavior changed in this PR. Record a verdict for every
candidate:

```text
- path/to/doc.md → possibly stale (describes behavior that changed)
Expand Down
4 changes: 3 additions & 1 deletion internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/docs-currency.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@ references to renamed/removed identifiers.

Extract identifiers from the diff, then search documentation files for
references. Flag docs that reference identifiers modified or removed in
this PR.
this PR. Also check whether documentation files covering the same
feature exist based on file name and directory structure — these may
need to reflect new behavior even if no identifier matches.

## Rename/deprecation pattern strategy

Expand Down
Loading