docs(project-context): say "pitfall" instead of "pitfall line" - #2709
Conversation
Drop the coined compound in favor of the plain word; adjust the five sentences in SKILL.md and best-practices.md that used it.
Greptile SummaryThe PR replaces the coined phrase “pitfall line” with “pitfall” in the project-context skill and its best-practices reference.
Confidence Score: 4/5The PR appears safe to merge, with a non-blocking documentation consistency issue in two related project-context pages. The changed wording preserves the skill's behavior and meaning, but the partial rename leaves two user-facing documents using the retired term. Files Needing Attention: src/bmm-skills/plan/bmad-project-context/SKILL.md and the related docs/how-to/project-context.md and docs/explanation/project-context-theory.md pages
|
| Filename | Overview |
|---|---|
| src/bmm-skills/plan/bmad-project-context/SKILL.md | Renames four uses of “pitfall line” consistently within the skill, but related documentation still uses the old phrase. |
| src/bmm-skills/plan/bmad-project-context/references/best-practices.md | Applies the same terminology simplification to the matching retention rule without changing its meaning. |
Prompt To Fix All With AI
### Issue 1
src/bmm-skills/plan/bmad-project-context/SKILL.md:3
**Terminology rename remains incomplete**
The skill now uses “pitfall,” but `docs/how-to/project-context.md:58` and `docs/explanation/project-context-theory.md:76` retain “pitfall line,” leaving readers with two names for the same concept.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "docs(project-context): say "pitfall" ins..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| --- | ||
| name: bmad-project-context | ||
| description: 'Set up, refresh, or audit a repository''s agent instructions (the AGENTS.md block) so AI agents work well in that repo. Also records observed agent mistakes as pitfall lines. Must be invoked by name.' | ||
| description: 'Set up, refresh, or audit a repository''s agent instructions (the AGENTS.md block) so AI agents work well in that repo. Also records observed agent mistakes as pitfalls. Must be invoked by name.' |
There was a problem hiding this comment.
The skill now uses “pitfall,” but docs/how-to/project-context.md:58 and docs/explanation/project-context-theory.md:76 retain “pitfall line,” leaving readers with two names for the same concept.
Prompt To Fix With AI
This is a comment left during a code review.
Path: src/bmm-skills/plan/bmad-project-context/SKILL.md
Line: 3
Comment:
**Terminology rename remains incomplete**
The skill now uses “pitfall,” but `docs/how-to/project-context.md:58` and `docs/explanation/project-context-theory.md:76` retain “pitfall line,” leaving readers with two names for the same concept.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
📝 WalkthroughWalkthroughThe project context skill and its best-practices reference now use “pitfall” terminology consistently instead of “pitfall line.” ChangesProject context terminology
Estimated code review effort: 1 (Trivial) | ~2 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/bmm-skills/plan/bmad-project-context/SKILL.md`:
- Line 3: Update the documentation references associated with the
project-context instructions to use the singular term “pitfall” instead of
“pitfall line” in both the how-to and theory documents. Preserve the surrounding
documentation and formatting.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: e1b0139b-9d0b-4108-90bc-ffffe869b5bd
📒 Files selected for processing (2)
src/bmm-skills/plan/bmad-project-context/SKILL.mdsrc/bmm-skills/plan/bmad-project-context/references/best-practices.md
| --- | ||
| name: bmad-project-context | ||
| description: 'Set up, refresh, or audit a repository''s agent instructions (the AGENTS.md block) so AI agents work well in that repo. Also records observed agent mistakes as pitfall lines. Must be invoked by name.' | ||
| description: 'Set up, refresh, or audit a repository''s agent instructions (the AGENTS.md block) so AI agents work well in that repo. Also records observed agent mistakes as pitfalls. Must be invoked by name.' |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
matches="$(rg -n -i '\bpitfall[[:space:]]+line\b' \
src/bmm-skills/plan/bmad-project-context docs 2>/dev/null || true)"
if [ -n "$matches" ]; then
printf '%s\n' "$matches"
exit 1
fiRepository: bmad-code-org/BMAD-METHOD
Length of output: 660
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- changed-file context ---'
sed -n '1,115p' src/bmm-skills/plan/bmad-project-context/SKILL.md
printf '%s\n' '--- matching documentation context ---'
sed -n '48,66p' docs/how-to/project-context.md
sed -n '68,82p' docs/explanation/project-context-theory.md
printf '%s\n' '--- all related terminology ---'
rg -n -i '\bpitfall([[:space:]]+line|[[:space:]]+lines?)\b|\bpolicy([[:space:]]+line|[[:space:]]+lines?)\b' \
src/bmm-skills/plan/bmad-project-context docs || trueRepository: bmad-code-org/BMAD-METHOD
Length of output: 11507
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- working-tree diff for the skill and documentation ---'
git diff -- src/bmm-skills/plan/bmad-project-context/SKILL.md docs
printf '%s\n' '--- remaining singular and plural terminology ---'
rg -n -i '\bpitfall(s)?\b' \
src/bmm-skills/plan/bmad-project-context docs || trueRepository: bmad-code-org/BMAD-METHOD
Length of output: 3959
Update stale documentation to use pitfall.
Replace pitfall line in docs/how-to/project-context.md:58 and docs/explanation/project-context-theory.md:76 with pitfall.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/bmm-skills/plan/bmad-project-context/SKILL.md` at line 3, Update the
documentation references associated with the project-context instructions to use
the singular term “pitfall” instead of “pitfall line” in both the how-to and
theory documents. Preserve the surrounding documentation and formatting.
Source: Path instructions
1 participant
What
Replaces the coined term "pitfall line" with plain "pitfall" throughout the bmad-project-context skill — four sentences in
SKILL.md(description, close step, record intent, audit rule) and the matching retention rule inreferences/best-practices.md.Why
"Pitfall" is ordinary English; compounding it into "pitfall line" made it a term of art the reader has to track without adding meaning. Grammar adjusted where needed; no behavioral change.