docs: tighten forge idea skill wording#2513
Conversation
🤖 Augment PR SummarySummary: This PR rewrites the Changes:
Technical Notes: No behavioral scripts or paths were changed; this is a documentation/skill-instructions tightening intended to reduce misfires from metaphorical phrasing. 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| - **Hardened** — the idea survived. Distill the memlog into `{workspace}/forged-idea.md`: super succinct — the locked items and what was killed and why, in the user's meaning. Not a prose retelling, not a template, not the conversation replayed — the load-bearing residue, nothing else. If it reads like a document, it's too long. Note it can feed `bmad-spec`, `bmad-prd`, or `bmad-prfaq`. | ||
| - **Killed** — the idea did not survive. Say so plainly and record why. Finding this cheaply is a win, not a failure. | ||
| - **Clearer** — the user simply thinks straighter now. The memlog stands on its own; no `forged-idea.md` needed (the report below still renders). | ||
| - **Hardened** — the idea is stronger and specific enough to use. Distill the memlog into `{workspace}/forged-idea.md`. Keep it extremely short: only the decisions, rejected options, and reasons that matter downstream, in the user's meaning. Do not write a prose summary, template, or conversation recap. If it reads like a document, it is too long. Note that it can feed `bmad-spec`, `bmad-prd`, or `bmad-prfaq`. |
There was a problem hiding this comment.
bmad-spec/bmad-prd/bmad-prfaq are referenced here without using explicit “invoke” language, which may violate REF-03 in the skill-validator ruleset. Consider rephrasing so any mention of other skills is framed as “Invoke the ... skill” (or equivalent) to avoid validation failures. (Rule: tools/skill-validator.md)
Severity: high
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
📝 WalkthroughWalkthroughRewrote the ChangesBmad Forge Idea Skill Rewrite
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 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
🧹 Nitpick comments (1)
src/core-skills/bmad-forge-idea/SKILL.md (1)
88-91: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider varying the sentence structure in the persona selection guidance.
Four successive conditional sentences beginning with "If" make this paragraph monotonous. Restructuring into a bulleted list or varying the phrasing would improve scannability.
✏️ Proposed rewording
- **One available persona** — choose an installed agent or user-defined persona whose expertise fits the current branch. Vary this voice every few turns; do not let one voice dominate. If the user names a specific persona, use it. If the user calls a saved party, use the whole party and its scene. If the user asks to go one-on-one, use only the requested persona. If no pool is available, generate this voice yourself. + **One available persona** — choose an installed agent or user-defined persona whose expertise fits the current branch. Vary this voice every few turns; do not let one voice dominate. Use the persona the user names; use the whole party and its scene when the user calls a saved party; use only the requested persona for one-on-one; generate this voice yourself when no pool is available.🤖 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/core-skills/bmad-forge-idea/SKILL.md` around lines 88 - 91, The persona selection guidance in the two-voices section is too repetitive because several consecutive sentences start with the same conditional phrasing. Rework that paragraph around the existing symbols “One available persona” and “One generated persona” by varying the sentence structure or converting the conditions into a bulleted list, while preserving the rules for installed personas, saved parties, one-on-one requests, and fallback generation.
🤖 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/core-skills/bmad-forge-idea/SKILL.md`:
- Around line 96-104: The exit flow in SKILL.md conflicts with the append-only
memlog contract by implying a frontmatter status update for completion. Change
the completion recording in the forge exit path to append an event entry (for
example via the memlog append flow) rather than setting a status field, and
update the “On Activation” resume logic to detect completion from the latest
event entry instead of frontmatter. Use the existing memlog/memlog.py contract,
the exit-state section, and the activation step 5 logic as the anchors for the
fix.
---
Nitpick comments:
In `@src/core-skills/bmad-forge-idea/SKILL.md`:
- Around line 88-91: The persona selection guidance in the two-voices section is
too repetitive because several consecutive sentences start with the same
conditional phrasing. Rework that paragraph around the existing symbols “One
available persona” and “One generated persona” by varying the sentence structure
or converting the conditions into a bulleted list, while preserving the rules
for installed personas, saved parties, one-on-one requests, and fallback
generation.
🪄 Autofix (Beta)
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
Run ID: 2fb84dfb-7e45-4184-a8ef-174f77cdbdfa
📒 Files selected for processing (1)
src/core-skills/bmad-forge-idea/SKILL.md
| ## Exits | ||
|
|
||
| The session ends however the thinking lands, and every landing is a real outcome: | ||
| The session can end in three valid states: | ||
|
|
||
| - **Hardened** — the idea survived. Distill the memlog into `{workspace}/forged-idea.md`: super succinct — the locked items and what was killed and why, in the user's meaning. Not a prose retelling, not a template, not the conversation replayed — the load-bearing residue, nothing else. If it reads like a document, it's too long. Note it can feed `bmad-spec`, `bmad-prd`, or `bmad-prfaq`. | ||
| - **Killed** — the idea did not survive. Say so plainly and record why. Finding this cheaply is a win, not a failure. | ||
| - **Clearer** — the user simply thinks straighter now. The memlog stands on its own; no `forged-idea.md` needed (the report below still renders). | ||
| - **Hardened** — the idea is stronger and specific enough to use. Distill the memlog into `{workspace}/forged-idea.md`. Keep it extremely short: only the decisions, rejected options, and reasons that matter downstream, in the user's meaning. Do not write a prose summary, template, or conversation recap. If it reads like a document, it is too long. Note that it can feed `bmad-spec`, `bmad-prd`, or `bmad-prfaq`. | ||
| - **Killed** — the idea does not hold up. Say so plainly and record why. Finding that out early is a valid outcome. | ||
| - **Clearer** — the user understands the idea better, but there is no hardened idea to hand off. Leave the memlog as the record; no `forged-idea.md` is needed. | ||
|
|
||
| However it lands, render the verdict as a self-contained HTML report the user can open — `{workspace}/forge-report.html`, written every time, no asking. Strike it with a bespoke wax-seal/stamp matched to the outcome: **HARDENED** for a survivor, an **Idea Death Certificate** stamped **KILLED** (with the cause of death) for one that didn't, or a fitting bespoke seal for wherever else it landed (e.g. **CLARIFIED**). Lay out the load-bearing residue — the locked items, what was killed and why, the cracks that held — in the user's meaning, and credit the room: the personas and parties that pressure-tested it, by name, icon, and voice. One nicely-styled page (inline CSS, an inline-SVG seal, light flourish only where it lifts the piece) — a genuine keepsake, not a templated dump. Tell the user the path. | ||
| Always render `{workspace}/forge-report.html` as a self-contained HTML file the user can open, with inline CSS and an inline-SVG seal or stamp. Summarize the outcome, the locked decisions, what was rejected and why, and the weak points that survived scrutiny, in the user's meaning. Credit the personas and parties that pressure-tested the idea by name, icon, and voice. Render a prominent wax-seal-style or stamped outcome mark, matched to the result: `HARDENED`, an `Idea Death Certificate` stamped `KILLED` with the cause of death, or `CLARIFIED`. Tell the user the path. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Exit session completion contradicts memlog append-only invariant.
The exit flow describes terminal states but relies on memlog.py set --key status --value complete (line 106, unchanged) to record completion. This mutates memlog frontmatter, violating the upstream memlog.py invariant #3: "No lifecycle status... never as frontmatter the log would have to mutate." The memlog design authority (src/scripts/memlog.py:5-67) and bmad-spec/SKILL.md both treat completion as an append-only --type event entry.
Align the forge exit with the memlog contract: record completion via append --type event --text "session complete" instead of set, and update the resume logic in "On Activation" step 5 to scan for the latest event entry rather than frontmatter status.
Based on learnings, the memlog is the authority on what was decided and on capability IDs. As per the memlog.py upstream contract, a memory log has no "complete" flag; whether the work is done is recorded as an entry, never as frontmatter the log would have to mutate.
🤖 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/core-skills/bmad-forge-idea/SKILL.md` around lines 96 - 104, The exit
flow in SKILL.md conflicts with the append-only memlog contract by implying a
frontmatter status update for completion. Change the completion recording in the
forge exit path to append an event entry (for example via the memlog append
flow) rather than setting a status field, and update the “On Activation” resume
logic to detect completion from the latest event entry instead of frontmatter.
Use the existing memlog/memlog.py contract, the exit-state section, and the
activation step 5 logic as the anchors for the fix.
2 participants
What
Tightens the wording in
bmad-forge-ideaso the skill is easier to read and less likely to misfire on ambiguous prompt language.Why
This mitigates Claude Footgun Syndrome: Claude's tendency to encode important instructions in metaphor and jargon. The original skill had strong behavior, but too much of it was hidden inside colorful phrasing that could be misread or over-performed.
How
Testing
Ran
npm ci && npm run quality.