chore(skills): convert review-edge-case-hunter.xml to native skill#1871
Merged
alexeyv merged 2 commits intobmad-code-org:mainfrom Mar 9, 2026
Merged
chore(skills): convert review-edge-case-hunter.xml to native skill#1871alexeyv merged 2 commits intobmad-code-org:mainfrom
alexeyv merged 2 commits intobmad-code-org:mainfrom
Conversation
Replace single-file XML task with skill directory format (SKILL.md + workflow.md + bmad-skill-manifest.yaml) following the pattern established by bmad-review-adversarial-general. Update all reference locations: bmad-skill-manifest.yaml, module-help.csv, step-04-review.md, and bmad-os-review-pr instructions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
🤖 Augment PR SummarySummary: Converts the Edge Case Hunter review task from XML to a native skill for consistency with other review skills. Changes:
Technical Notes: Intended to be behavior-preserving; the workflow keeps the same strict JSON-only output contract (4 fields, no extra text). 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| ### 1.2 Run Edge Case Hunter (subagent) | ||
|
|
||
| Spawn a subagent that executes the task defined in `_bmad/core/tasks/review-edge-case-hunter.xml`. Pass the full PR diff as the `content` input. Omit `also_consider` unless the user specified extra focus areas. | ||
| Spawn a subagent that invokes the `bmad-review-edge-case-hunter` skill. Pass the full PR diff as the `content` input. Omit `also_consider` unless the user specified extra focus areas. |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Collaborator
Author
There was a problem hiding this comment.
Fixed in 8be8123 — changed to "The skill returns".
📝 WalkthroughWalkthroughThe PR migrates the edge-case-hunter review from an XML-based task definition to a markdown-based skill format, removing the original task file and creating new skill files with corresponding manifest entries, while updating workflow callers to reference the new skill. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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: 9
🧹 Nitpick comments (1)
src/core/tasks/bmad-review-edge-case-hunter/bmad-skill-manifest.yaml (1)
1-1: Pick one source of truth for the skill metadata.Keeping only
type: skillhere forces the name/description to live in bothsrc/core/tasks/bmad-skill-manifest.yamlandsrc/core/tasks/bmad-review-edge-case-hunter/SKILL.md, and they already drifted in this PR. Generate one from the other or keep the user-facing description in one place.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/tasks/bmad-review-edge-case-hunter/bmad-skill-manifest.yaml` at line 1, Choose a single source of truth for the skill metadata: either keep canonical name/description in the YAML (bmad-skill-manifest.yaml) and remove or reference them from src/core/tasks/bmad-review-edge-case-hunter/SKILL.md, or keep SKILL.md as the canonical user-facing description and remove duplicate fields from bmad-skill-manifest.yaml; update the repository so only one location contains the authoritative name/description and adjust any code that reads metadata (the manifest reader or SKILL.md consumer) to load from that chosen source, or add a small generator that creates one from the other to keep them in sync.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md`:
- Around line 30-34: Update the no-subagent fallback in step-04-review.md so it
references the actual edge-case hunter contract and reproduces its JSON-only
four-field prompt format: replace the current role-blurb-only instructions with
a pointer or inclusion of the same contract used by
src/core/tasks/bmad-review-edge-case-hunter/workflow.md (the exact JSON schema
the skill expects) and ensure the fallback generates three review prompt files
that conform to that four-field JSON contract for each reviewer role (Blind
hunter, Edge case hunter, Acceptance auditor) before halting; keep the rest of
the fallback behavior (three files, separate sessions, paste back findings)
unchanged.
In `@src/core/tasks/bmad-review-edge-case-hunter/SKILL.md`:
- Around line 1-4: The SKILL.md frontmatter for name:
bmad-review-edge-case-hunter has diverged from the public manifest text; update
the description field in SKILL.md to match the original description in
src/core/tasks/bmad-skill-manifest.yaml (lines referencing the same skill) so
metadata is behavior-preserving, i.e., replace the added positioning text with
the exact manifest description string for bmad-review-edge-case-hunter and
ensure the frontmatter keys (name, description) and punctuation remain identical
to the manifest entry.
In `@src/core/tasks/bmad-review-edge-case-hunter/workflow.md`:
- Around line 29-30: Clarify and codify the precedence and scope behavior for
the `also_consider` input relative to "diff mode": update the workflow text so
it unambiguously states whether `also_consider` may expand the analysis beyond
diff hunks or is restricted to the diff, and if expansion is allowed, define how
it merges with diff scanning (e.g., union of diff hunk ranges and
`also_consider` areas, or diff-only with `also_consider` providing annotations
only). Specifically amend the lines referencing "diff mode" and "Step 2" so the
rules for `also_consider` are explicit (e.g., precedence, conflict resolution,
and deterministic ordering) to ensure two executions with the same inputs always
produce the same scope.
- Around line 21-23: Current behavior treats empty or undecodable review input
as "no findings" by returning [], which hides malformed or missing
`{diff_output}`; change the logic that "Load the content to review strictly from
provided input" so that when input is empty, missing, or cannot be decoded as
text the code returns a distinct error signal (throw an exception or return a
structured error object like {error: "bad_input", reason: "..."}), rather than
`[]`, and keep `[]` reserved only for legitimately reviewed content with zero
findings; update any callers of this workflow to handle the new error signal so
the edge-case pass fails closed instead of being silently suppressed.
- Around line 4-6: Update the "When a diff is provided" rule to explicitly treat
deleted guards as missing protections: state that any validation or guard
condition removed in a diff hunk (i.e., deletion hunks that remove checks
referenced as "guards in the diff") should be considered equivalent to "lack an
explicit guard" and thus must cause the workflow to list the reachable boundary
as a potential edge-case regression; ensure the guidance tells the scanner to
detect deletion hunks that remove guard expressions and include those boundaries
in the output even if the guard itself no longer exists in the new content.
- Around line 36-39: The "validate completeness" Step 3 is missing mandatory
edge classes (overflow, type coercion, concurrency, timing) so update the
workflow text to make Step 3 truly exhaustive: modify the list under Step 3 (the
lines that currently mention conditionals, inputs, and loops) to explicitly
include checks for arithmetic overflow/underflow, integer/float and string
coercion cases, concurrency/race and ordering scenarios, and
timing/timeout/latency-induced behavior; also instruct the reviewer to add
specific test/action items for each class (e.g., overflow bounds, type-casting
paths, concurrent access patterns, timing windows) and ensure newly discovered
paths are recorded to findings while confirmed-handled ones are removed.
- Around line 1-64: The workflow file lacks required YAML frontmatter so
getWorkflowsFromPath in manifest-generator.js will skip it; add minimal YAML
frontmatter to the top of
src/core/tasks/bmad-review-edge-case-hunter/workflow.md (e.g., required keys
like title and description or whatever the manifest-generator expects) so the
installer no longer treats the file as invalid; if unsure which keys are
required, inspect getWorkflowsFromPath and the manifest schema in BMAD-METHOD to
mirror its expected frontmatter fields.
- Around line 3-6: The rule line "**Don't require the guard to appear inside the
diff itself.**" is causing false positives by insisting guards must be located
within the changed hunks; update the guard-detection logic so that when
evaluating a diff it also searches a configurable window of surrounding
unchanged context (or consults the referenced project-level review guidance)
rather than only the diff hunk itself; concretely, change the function that
enforces this rule (the guard-presence check invoked for the
bmad-review-edge-case-hunter workflow) to accept and scan nearby unchanged lines
or to relax the constraint so a guard found outside the diff satisfies the
requirement.
In `@src/core/tasks/bmad-skill-manifest.yaml`:
- Around line 21-24: The manifest renamed the registry entry to
"bmad-review-edge-case-hunter" but removed the old public key
"review-edge-case-hunter.xml", which is a breaking change; restore backward
compatibility by adding a compatibility alias or redirect entry that maps the
old name "review-edge-case-hunter.xml" to the new canonicalId
"bmad-review-edge-case-hunter" (e.g., add an additional key or alias field
alongside canonicalId for "review-edge-case-hunter.xml" so callers that
reference the old name still resolve to the "bmad-review-edge-case-hunter"
skill).
---
Nitpick comments:
In `@src/core/tasks/bmad-review-edge-case-hunter/bmad-skill-manifest.yaml`:
- Line 1: Choose a single source of truth for the skill metadata: either keep
canonical name/description in the YAML (bmad-skill-manifest.yaml) and remove or
reference them from src/core/tasks/bmad-review-edge-case-hunter/SKILL.md, or
keep SKILL.md as the canonical user-facing description and remove duplicate
fields from bmad-skill-manifest.yaml; update the repository so only one location
contains the authoritative name/description and adjust any code that reads
metadata (the manifest reader or SKILL.md consumer) to load from that chosen
source, or add a small generator that creates one from the other to keep them in
sync.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 16075681-046e-4297-85ce-a6d1c927fba2
⛔ Files ignored due to path filters (2)
.claude/skills/bmad-os-review-pr/prompts/instructions.mdis excluded by!.claude/**src/core/module-help.csvis excluded by!**/*.csv
📒 Files selected for processing (6)
src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.mdsrc/core/tasks/bmad-review-edge-case-hunter/SKILL.mdsrc/core/tasks/bmad-review-edge-case-hunter/bmad-skill-manifest.yamlsrc/core/tasks/bmad-review-edge-case-hunter/workflow.mdsrc/core/tasks/bmad-skill-manifest.yamlsrc/core/tasks/review-edge-case-hunter.xml
💤 Files with no reviewable changes (1)
- src/core/tasks/review-edge-case-hunter.xml
src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md
Show resolved
Hide resolved
Comment on lines
+1
to
+4
| --- | ||
| name: bmad-review-edge-case-hunter | ||
| description: 'Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven.' | ||
| --- |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Collaborator
Author
There was a problem hiding this comment.
Rejected — SKILL.md frontmatter is the source of truth for descriptions, not the central manifest. No drift issue.
There was a problem hiding this comment.
@alexeyv, understood — I'll note that for future reviews.
✏️ Learnings added
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1871
File: src/core/tasks/bmad-review-edge-case-hunter/SKILL.md:1-4
Timestamp: 2026-03-09T14:19:46.193Z
Learning: In BMAD-METHOD, SKILL.md frontmatter is the canonical source of truth for skill descriptions (name, description fields). The central manifest (e.g., src/core/tasks/bmad-skill-manifest.yaml) is not authoritative for description text. Reviewers must not flag differences between SKILL.md frontmatter descriptions and the central manifest description as "drift" or a behavior-preserving violation.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1834
File: src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml:3-3
Timestamp: 2026-03-06T22:45:46.460Z
Learning: In BMAD-METHOD, the `description` field in `bmad-skill-manifest.yaml` files (e.g., `src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml`) follows a concise, action-oriented convention consistent across all manifests in the project. Descriptions like "Perform adversarial code review finding specific issues" are intentionally brief and do not need to enumerate output format details (e.g., severity tags, line-by-line approach). Adding implementation-specific wording such as "line-by-line" would be inaccurate. Reviewers should not flag these descriptions as generic or request additional output/format details.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md:141-149
Timestamp: 2026-03-06T01:57:16.795Z
Learning: In BMAD-METHOD step-02-design-epics.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md), Step C's file overlap review intentionally relies on the agent's contextual judgment rather than a formal file-enumeration procedure. The agent derives file modification lists from the architecture and PRD it used to design the epics, so no explicit enumeration step is needed. Reviewers should not flag the absence of a formal file-sourcing procedure in Step C.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: src/bmm/workflows/4-implementation/create-story/discover-inputs.md:63-67
Timestamp: 2026-03-09T00:01:18.740Z
Learning: In BMAD-METHOD discover-inputs.md (src/bmm/workflows/4-implementation/create-story/discover-inputs.md and src/bmm/workflows/4-implementation/code-review/discover-inputs.md), the whole-document fallback (Step 2b) intentionally loads ALL glob matches into {pattern_name_content} rather than selecting a single canonical file. This is deliberate design — the reporting step (Step 3) and LLM context handling are relied upon to mitigate contradictory sources. Reviewers should not flag the absence of a canonical-match or deduplication rule in the whole-document fallback.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, source skill directories (those collected by the `type: skill` manifest pipeline) never contain a `SKILL.md` file. Therefore, in `installVerbatimSkills` (`tools/cli/installers/lib/ide/_config-driven.js`), writing the generated SKILL.md before calling `fs.copy()` for the directory contents is safe — there is no risk of a source `SKILL.md` overwriting the generated YAML-safe one. Reviewers should not flag this write-before-copy ordering as a bug.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the input-trust guardrail (line 17: "may contain hallucinations, scope creep, or unvalidated assumptions. Follow the workflow exactly...") is intentionally advisory, not a hard enforcement gate. Enforcement is provided by the surrounding workflow structure: the mandatory clarify loop (Step 2 clarify intent), codebase investigation, and the human checkpoint in Step 2. Reviewers should not flag this guardrail as non-operational or require it to include a mandatory verification sub-step.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md:113-118
Timestamp: 2026-03-06T02:00:37.190Z
Learning: In BMAD-METHOD, step-04-final-validation.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md) runs in the same single LLM agent session as step-02 (epic design) and step-03 (story creation). The agent retains full in-context knowledge of the architecture, PRD, and all epics/stories it designed. Validation checks such as the File Churn Check (Epic Structure Validation) do not require formal serialized data structures (e.g., affected_files arrays, rationale template fields, or numeric overlap thresholds) because the agent can assess file overlap and recall consolidation decisions from its own session context. Reviewers should not flag the absence of these structures as making the validation unexecutable.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1807
File: src/bmm/workflows/bmad-quick-flow/quick-dev2/steps/step-04-review.md:30-30
Timestamp: 2026-03-02T23:53:11.419Z
Learning: In BMAD-METHOD quick-dev2 workflow, one-shot mode relies on session knowledge: the agent executing step-03-implement.md tracks which files it modified in-session, and step-04-review.md invokes `{adversarial_review_task}` with those changed files without constructing a VCS diff. The `baseline_commit` mechanism is only used in plan-code-review mode, not one-shot.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:40-47
Timestamp: 2026-03-08T13:17:18.978Z
Learning: In BMAD-METHOD, sharded document inputs (e.g., `*prd*/*.md`, `*epic*/*.md`, `*architecture*/*.md`, `*ux*/*.md`) in workflow input tables are doc-convention glob patterns illustrating the directory structure, not independent behavioral contracts. The actual discovery algorithm for sharded documents always requires an `index.md` entry point within the sharded directory. This is an intentional, project-wide convention used consistently across all workflows. Reviewers should not flag the glob patterns in input tables as mismatched with the index.md-based discovery logic.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:154-180
Timestamp: 2026-03-08T17:15:55.392Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the mixed severity terminology — "CRITICAL finding" used in Step 3 execution logic while the categorization action and output template use "HIGH/MEDIUM/LOW" — is a pre-existing inconsistency inherited verbatim from the original instructions.xml. It is not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag this terminology mismatch during format conversion PRs; any normalization of severity levels should be addressed in a dedicated behavioral follow-up PR.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md:118-118
Timestamp: 2026-03-06T02:01:48.853Z
Learning: In BMAD-METHOD step-04-final-validation.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md), the File Churn Check's RIGHT pattern uses natural language terms such as "distinct files/components" and "consolidation was explicitly considered and rejected with rationale." These terms are intentionally left without formal definitions, numeric overlap thresholds, or required metadata fields. The AI agent executing step-04 runs in the same session as step-02 and step-03 and retains full in-context knowledge of the epic structure; it assesses partial file overlap and component boundaries through contextual judgment. Adding explicit percentage thresholds or structured rationale fields would over-specify the prompt without improving output quality. Reviewers should not flag these terms as ambiguous or request threshold-based or metadata-field additions.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, the `installVerbatimSkills` method in `tools/cli/installers/lib/ide/_config-driven.js` hardcodes `workflow.md` as the skill entry file in the generated SKILL.md launcher intentionally. The `type: skill` manifest pipeline guarantees that `workflow.md` is always the canonical entry file for verbatim skill directories; no other entry file names (e.g., `workflow.yaml`, `workflow-*.md`) are possible. Reviewers should not flag this hardcoded reference as a bug or suggest dynamic entry-file detection.
Learnt from: n-zhi
Repo: bmad-code-org/BMAD-METHOD PR: 1817
File: tools/cli/installers/lib/ide/templates/combined/antigravity-agent.md:5-5
Timestamp: 2026-03-05T12:14:43.190Z
Learning: In BMAD-METHOD, the instruction "NEVER break character until given an exit command" in antigravity-agent.md (tools/cli/installers/lib/ide/templates/combined/antigravity-agent.md) is a pre-existing pattern inherited from the corresponding default-*.md template. It is not introduced by PR `#1817`. A future dedicated PR should replace this absolute constraint with a bounded formulation (e.g., "stay in role unless overridden by higher-priority instructions or an exit command") across all affected default-*.md and antigravity-*.md templates.
Learnt from: wsmoak
Repo: bmad-code-org/BMAD-METHOD PR: 1729
File: tools/cli/installers/lib/ide/codex.js:265-265
Timestamp: 2026-02-21T13:18:49.398Z
Learning: In tools/cli/installers/lib/ide/codex.js transformToSkillFormat method, the description field is required in the Agent Skills format. Empty strings should be replaced with the default value `${skillName} skill`, so the logical OR operator (||) is intentionally used instead of nullish coalescing (??).
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1834
File: src/bmm/workflows/generate-project-context/bmad-skill-manifest.yaml:1-3
Timestamp: 2026-03-06T22:45:58.474Z
Learning: In BMAD-METHOD, canonicalId uniqueness across bmad-skill-manifest.yaml files is considered enforced by the naming convention (all IDs carry the `bmad-` prefix plus a unique workflow/agent path-derived suffix). Automated duplicate-detection tooling (e.g., in validate-agent-schema.js or CI) is intentionally deferred and should not be flagged in PRs as a blocking concern. The maintainer (alexeyv) considers the convention a sufficient structural safeguard.
Learnt from: n-zhi
Repo: bmad-code-org/BMAD-METHOD PR: 1817
File: tools/cli/installers/lib/ide/templates/combined/antigravity-agent.md:2-2
Timestamp: 2026-03-05T12:13:33.566Z
Learning: In BMAD-METHOD, the double-quote escaping of `{{description}}` placeholders in Antigravity templates (e.g., tools/cli/installers/lib/ide/templates/combined/antigravity-agent.md and siblings) is a known out-of-scope issue for PR `#1817`. A future PR should add an `escapeYamlDoubleQuote` helper in `tools/cli/installers/lib/ide/_config-driven.js` and apply it wherever `{{description}}` is interpolated (including agent-command-generator.js, workflow-command-generator.js, and task-tool-command-generator.js) to prevent YAML frontmatter corruption when descriptions contain embedded double quotes or backslashes.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1859
File: tools/cli/installers/lib/core/manifest-generator.js:0-0
Timestamp: 2026-03-08T14:54:51.859Z
Learning: In BMAD-METHOD (`tools/cli/installers/lib/core/manifest-generator.js`), skill `canonicalId` is derived exclusively from the directory name (`path.basename(dir)`), never from the `bmad-skill-manifest.yaml`. If a skill manifest contains a `canonicalId` field, the code emits a `console.warn` and ignores it. Reviewers must not flag the absence of a manifest-provided `canonicalId` for skills, and must not suggest falling back to or synthesizing an ID from any other source.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1850
File: docs/how-to/quick-fixes.md:41-47
Timestamp: 2026-03-07T23:11:09.292Z
Learning: In BMAD-METHOD, agents and skills have a defined architectural relationship: agents are invoked via their skill entry point. For example, `bmad-quick-flow-solo-dev` is both the agent name and the skill used to invoke it. There is no ambiguity or overlap between "agent skills" and "workflow skills" in docs — reviewers should not flag agent invocations (e.g., `bmad-quick-flow-solo-dev`) as conflicting with standalone workflow skills (e.g., `bmad-quick-spec`). The architecture documentation defines this relationship explicitly.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md:121-124
Timestamp: 2026-03-06T02:04:11.275Z
Learning: In BMAD-METHOD step-02-design-epics.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md), the Step A guidance ("outcome is certain", "validated design", "direction changes between epics are unlikely") at lines 121-124 is collaborative facilitation language, not autonomous agent evaluation criteria. The agent surfaces these topics to the user in dialogue; the user asserts design completeness and risk level. Adding operational rubrics, quantified thresholds, or per-artifact checklists to these phrases would contradict the workflow's explicit dialogue-first design (see lines 42-44: "We engage in collaborative dialogue, not command-response"). Reviewers should not flag these phrases as undefined or missing decision logic.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1834
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/bmad-skill-manifest.yaml:1-3
Timestamp: 2026-03-06T22:45:40.932Z
Learning: In BMAD-METHOD, bmad-skill-manifest.yaml files (e.g., src/bmm/workflows/3-solutioning/create-epics-and-stories/bmad-skill-manifest.yaml) are intentionally minimal with exactly 3 fields: canonicalId, type, and description. Adding a schemaVersion field or formal schema validation to these manifests is considered premature engineering by the maintainers — the format is trivially simple, has no history of breaking changes, and versioning can be deferred until genuinely needed. Reviewers should not flag the absence of schemaVersion or formal validation logic in these manifest files.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: tools/cli/installers/lib/core/manifest-generator.js:347-354
Timestamp: 2026-03-09T00:01:20.628Z
Learning: In BMAD-METHOD `tools/cli/installers/lib/core/manifest-generator.js`, `getWorkflowsFromPath()` silently skips `workflow.md` files that lack YAML frontmatter (via `continue`). This is intentional: all valid workflow.md files are structurally required to have frontmatter, so files without it are invalid by convention and should be skipped. Reviewers must not flag this silent skip as a missing error or warning — the existing debug log is sufficient and a hard error is not warranted.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/core/manifest-generator.js:248-265
Timestamp: 2026-03-08T08:10:11.355Z
Learning: In `tools/cli/installers/lib/core/manifest-generator.js`, the `writeFilesManifest()` fallback path (using `this.files` when `installedFiles` is empty) is never reached in production. All real installs supply a comprehensive `installedFiles` array (including skill files) to `generateManifests()`, so the `this.files.push(...)` omission in the skill branch of `getWorkflowsFromPath()` has no practical impact. Do not flag this as a bug in future reviews.
Learnt from: n-zhi
Repo: bmad-code-org/BMAD-METHOD PR: 1817
File: tools/cli/installers/lib/ide/templates/combined/antigravity-agent.md:9-9
Timestamp: 2026-03-05T12:15:19.378Z
Learning: In BMAD-METHOD, the instruction "READ its entire contents" in antigravity-agent.md (tools/cli/installers/lib/ide/templates/combined/antigravity-agent.md) and its sibling antigravity-*.md templates is a pre-existing pattern inherited from the corresponding default-*.md templates. It is not introduced by PR `#1817`. A future dedicated PR should replace this unbounded-read directive with bounded-read semantics (e.g., chunking or a token/byte limit) across all affected default-*.md and antigravity-*.md templates, to prevent context-limit failures on large artifacts.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md:5-5
Timestamp: 2026-03-08T08:10:08.024Z
Learning: In BMAD-METHOD, `./` relative path references in skill step files under `src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/*.md` (and similar skill-format workflow step files) are resolved relative to the skill root directory, not relative to the step file's own directory. For example, `templateFile: './tech-spec-template.md'` in `step-02-plan.md` resolves to `<skill-root>/tech-spec-template.md`, not `<skill-root>/steps/tech-spec-template.md`. This convention is consistent and intentional across all skill-format step files and should not be flagged as ambiguous or fragile.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:27-30
Timestamp: 2026-03-08T13:17:16.749Z
Learning: In BMAD-METHOD correct-course workflow (src/bmm/workflows/4-implementation/correct-course/workflow.md), the "DOCUMENT OUTPUT" contract line ("Updated epics, stories, or PRD sections...") is wording carried over verbatim from the original instructions.md during the yaml-to-md format conversion PR `#1858`. It is a pre-existing limitation, not a regression introduced by the conversion. Reviewers should not flag this narrower output contract during format conversion PRs; any expansion of the contract to include Architecture/UI/UX changes and Sprint Change Proposal file should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:60-65
Timestamp: 2026-03-08T17:15:52.768Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the `{{story_path}}` input parameter used in Step 1 ("Use provided {{story_path}} or ask user which story file to review") is not declared in the Input Files table or Configuration Loading section. This is a pre-existing issue inherited from the original instructions.xml, not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag the absence of a formal `{{story_path}}` declaration in conversion PRs; any addition of this parameter to the inputs table should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1862
File: src/bmm/workflows/4-implementation/create-story/workflow.md:63-66
Timestamp: 2026-03-08T18:12:34.673Z
Learning: In BMAD-METHOD create-story workflow (src/bmm/workflows/4-implementation/create-story/workflow.md), the `GOTO step 2a` references throughout Step 1 (and corresponding locations at lines 89-97, 159, 216) are pre-existing issues inherited verbatim from the original instructions.xml. The original instructions.xml (commit 09ce855) already had `GOTO step 2a` at lines 24, 50, 55, 117, and 174 but defined only `<step n="2">` — no `<step n="2a">` label existed. This is not a regression introduced by the yaml-to-md conversion PR `#1862`. Reviewers should not flag these GOTO targets as a conversion regression; any fix should be addressed in a dedicated behavioral follow-up PR.
Learnt from: muratkeremozcan
Repo: bmad-code-org/BMAD-METHOD PR: 1367
File: src/bmm/workflows/testarch/test-design/instructions.md:304-307
Timestamp: 2026-01-22T18:34:14.142Z
Learning: When documenting cross-reference patterns in Markdown, ensure header anchors follow GitHub's anchor generation rules: lowercase, spaces to hyphens, remove emojis/special characters, and strip leading/trailing hyphens. Example: '### 🚨 R-001: Title' becomes '#r-001-title'. Use anchors that reflect these rules in documentation across Markdown files.
Comment on lines
+1
to
+64
| # Edge Case Hunter Review | ||
|
|
||
| **Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling. | ||
| When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff. | ||
| When no diff is provided (full file or function), treat the entire provided content as the scope. | ||
| Ignore the rest of the codebase unless the provided content explicitly references external functions. | ||
|
|
||
| **Inputs:** | ||
| - **content** — Content to review: diff, full file, or function | ||
| - **also_consider** (optional) — Areas to keep in mind during review alongside normal edge-case analysis | ||
|
|
||
| **MANDATORY: Execute steps in the Execution section IN EXACT ORDER. DO NOT skip steps or change the sequence. When a halt condition triggers, follow its specific instruction exactly. Each action within a step is a REQUIRED action to complete that step.** | ||
|
|
||
| **Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition. Trace each branching path: conditionals, switches, early returns, guard clauses, loops, error handlers. Trace each boundary condition: null, undefined, empty, zero, negative, overflow, max-length, type coercion, concurrency, timing. Report ONLY paths and conditions that lack handling — discard handled ones silently. Do NOT editorialize or add filler — findings only.** | ||
|
|
||
|
|
||
| ## EXECUTION | ||
|
|
||
| ### Step 1: Receive Content | ||
|
|
||
| - Load the content to review strictly from provided input | ||
| - If content is empty, or cannot be decoded as text, return empty array `[]` and stop | ||
| - Identify content type (diff, full file, or function) to determine scope rules | ||
|
|
||
| ### Step 2: Exhaustive Path Analysis | ||
|
|
||
| **Walk every branching path and boundary condition within scope — report only unhandled ones.** | ||
|
|
||
| - If `also_consider` input was provided, incorporate those areas into the analysis | ||
| - Enumerate all branching paths and boundary conditions within scope: conditionals, switches, early returns, guard clauses, loops, error handlers, null/empty states, overflow, type edges, concurrency, timing | ||
| - For each path: determine whether the content handles it | ||
| - Collect only the unhandled paths as findings — discard handled ones silently | ||
|
|
||
| ### Step 3: Validate Completeness | ||
|
|
||
| - Recheck every conditional for missing else/default | ||
| - Recheck every input for null/empty/wrong-type | ||
| - Recheck loop bounds for off-by-one and empty-collection | ||
| - Add any newly found unhandled paths to findings; discard confirmed-handled ones | ||
|
|
||
| ### Step 4: Present Findings | ||
|
|
||
| Output findings as a JSON array following the Output Format specification exactly. | ||
|
|
||
|
|
||
| ## OUTPUT FORMAT | ||
|
|
||
| Return ONLY a valid JSON array of objects. Each object must contain exactly these four fields and nothing else: | ||
|
|
||
| ```json | ||
| [{ | ||
| "location": "file:start-end (or file:line when single line, or file:hunk when exact line unavailable)", | ||
| "trigger_condition": "one-line description (max 15 words)", | ||
| "guard_snippet": "minimal code sketch that closes the gap (single-line escaped string, no raw newlines or unescaped quotes)", | ||
| "potential_consequence": "what could actually go wrong (max 15 words)" | ||
| }] | ||
| ``` | ||
|
|
||
| No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when no unhandled paths are found. | ||
|
|
||
|
|
||
| ## HALT CONDITIONS | ||
|
|
||
| - If content is empty or cannot be decoded as text, return empty array `[]` and stop |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Collaborator
Author
There was a problem hiding this comment.
Rejected — skill directories are discovered via SKILL.md + bmad-skill-manifest.yaml, not as standalone workflows. collectSkills claims the directory before getWorkflowsFromPath runs.
There was a problem hiding this comment.
@alexeyv, understood — thank you for the correction. The frontmatter guard in getWorkflowsFromPath is irrelevant here because collectSkills() claims the directory first via SKILL.md + bmad-skill-manifest.yaml, so workflow.md inside a skill directory is never subject to the standalone-workflow discovery path.
✏️ Learnings added
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1871
File: src/core/tasks/bmad-review-edge-case-hunter/workflow.md:0-0
Timestamp: 2026-03-09T14:19:52.005Z
Learning: In BMAD-METHOD, the YAML frontmatter requirement for `workflow.md` files (enforced by `getWorkflowsFromPath()` in `tools/cli/installers/lib/core/manifest-generator.js`) applies only to standalone workflow directories, NOT to `workflow.md` files inside skill directories. Skill directories are discovered by `collectSkills()` via `SKILL.md` + `bmad-skill-manifest.yaml` before `getWorkflowsFromPath()` runs, so the frontmatter guard never fires for skill-type `workflow.md` files. Reviewers must not flag missing YAML frontmatter in `workflow.md` files that reside inside skill directories (i.e., directories containing `SKILL.md` and `bmad-skill-manifest.yaml`).
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the input-trust guardrail (line 17: "may contain hallucinations, scope creep, or unvalidated assumptions. Follow the workflow exactly...") is intentionally advisory, not a hard enforcement gate. Enforcement is provided by the surrounding workflow structure: the mandatory clarify loop (Step 2 clarify intent), codebase investigation, and the human checkpoint in Step 2. Reviewers should not flag this guardrail as non-operational or require it to include a mandatory verification sub-step.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: src/bmm/workflows/4-implementation/create-story/discover-inputs.md:63-67
Timestamp: 2026-03-09T00:01:18.740Z
Learning: In BMAD-METHOD discover-inputs.md (src/bmm/workflows/4-implementation/create-story/discover-inputs.md and src/bmm/workflows/4-implementation/code-review/discover-inputs.md), the whole-document fallback (Step 2b) intentionally loads ALL glob matches into {pattern_name_content} rather than selecting a single canonical file. This is deliberate design — the reporting step (Step 3) and LLM context handling are relied upon to mitigate contradictory sources. Reviewers should not flag the absence of a canonical-match or deduplication rule in the whole-document fallback.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md:141-149
Timestamp: 2026-03-06T01:57:16.795Z
Learning: In BMAD-METHOD step-02-design-epics.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md), Step C's file overlap review intentionally relies on the agent's contextual judgment rather than a formal file-enumeration procedure. The agent derives file modification lists from the architecture and PRD it used to design the epics, so no explicit enumeration step is needed. Reviewers should not flag the absence of a formal file-sourcing procedure in Step C.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: tools/cli/installers/lib/core/manifest-generator.js:347-354
Timestamp: 2026-03-09T00:01:20.628Z
Learning: In BMAD-METHOD `tools/cli/installers/lib/core/manifest-generator.js`, `getWorkflowsFromPath()` silently skips `workflow.md` files that lack YAML frontmatter (via `continue`). This is intentional: all valid workflow.md files are structurally required to have frontmatter, so files without it are invalid by convention and should be skipped. Reviewers must not flag this silent skip as a missing error or warning — the existing debug log is sufficient and a hard error is not warranted.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:27-30
Timestamp: 2026-03-08T13:17:16.749Z
Learning: In BMAD-METHOD correct-course workflow (src/bmm/workflows/4-implementation/correct-course/workflow.md), the "DOCUMENT OUTPUT" contract line ("Updated epics, stories, or PRD sections...") is wording carried over verbatim from the original instructions.md during the yaml-to-md format conversion PR `#1858`. It is a pre-existing limitation, not a regression introduced by the conversion. Reviewers should not flag this narrower output contract during format conversion PRs; any expansion of the contract to include Architecture/UI/UX changes and Sprint Change Proposal file should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:154-180
Timestamp: 2026-03-08T17:15:55.392Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the mixed severity terminology — "CRITICAL finding" used in Step 3 execution logic while the categorization action and output template use "HIGH/MEDIUM/LOW" — is a pre-existing inconsistency inherited verbatim from the original instructions.xml. It is not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag this terminology mismatch during format conversion PRs; any normalization of severity levels should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1834
File: src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml:3-3
Timestamp: 2026-03-06T22:45:46.460Z
Learning: In BMAD-METHOD, the `description` field in `bmad-skill-manifest.yaml` files (e.g., `src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml`) follows a concise, action-oriented convention consistent across all manifests in the project. Descriptions like "Perform adversarial code review finding specific issues" are intentionally brief and do not need to enumerate output format details (e.g., severity tags, line-by-line approach). Adding implementation-specific wording such as "line-by-line" would be inaccurate. Reviewers should not flag these descriptions as generic or request additional output/format details.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:40-47
Timestamp: 2026-03-08T13:17:18.978Z
Learning: In BMAD-METHOD, sharded document inputs (e.g., `*prd*/*.md`, `*epic*/*.md`, `*architecture*/*.md`, `*ux*/*.md`) in workflow input tables are doc-convention glob patterns illustrating the directory structure, not independent behavioral contracts. The actual discovery algorithm for sharded documents always requires an `index.md` entry point within the sharded directory. This is an intentional, project-wide convention used consistently across all workflows. Reviewers should not flag the glob patterns in input tables as mismatched with the index.md-based discovery logic.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:60-65
Timestamp: 2026-03-08T17:15:52.768Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the `{{story_path}}` input parameter used in Step 1 ("Use provided {{story_path}} or ask user which story file to review") is not declared in the Input Files table or Configuration Loading section. This is a pre-existing issue inherited from the original instructions.xml, not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag the absence of a formal `{{story_path}}` declaration in conversion PRs; any addition of this parameter to the inputs table should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:18-30
Timestamp: 2026-03-08T13:17:11.250Z
Learning: In BMAD-METHOD, workflow.md files under src/bmm/workflows/ do not validate required config keys (e.g., planning_artifacts, communication_language, document_output_language, user_name) at initialization. The installer guarantees these keys are present in {project-root}/_bmad/bmm/config.yaml before any workflow runs, and downstream HALT conditions (e.g., in Document Discovery and step 1) catch practical failures. Adding per-workflow config validation guards would be inconsistent with all sibling workflows and is not required. Reviewers should not flag the absence of inline config-key validation in these workflow files.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, the `installVerbatimSkills` method in `tools/cli/installers/lib/ide/_config-driven.js` hardcodes `workflow.md` as the skill entry file in the generated SKILL.md launcher intentionally. The `type: skill` manifest pipeline guarantees that `workflow.md` is always the canonical entry file for verbatim skill directories; no other entry file names (e.g., `workflow.yaml`, `workflow-*.md`) are possible. Reviewers should not flag this hardcoded reference as a bug or suggest dynamic entry-file detection.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, source skill directories (those collected by the `type: skill` manifest pipeline) never contain a `SKILL.md` file. Therefore, in `installVerbatimSkills` (`tools/cli/installers/lib/ide/_config-driven.js`), writing the generated SKILL.md before calling `fs.copy()` for the directory contents is safe — there is no risk of a source `SKILL.md` overwriting the generated YAML-safe one. Reviewers should not flag this write-before-copy ordering as a bug.
Learnt from: n-zhi
Repo: bmad-code-org/BMAD-METHOD PR: 1817
File: tools/cli/installers/lib/ide/templates/combined/antigravity-workflow-yaml.md:11-11
Timestamp: 2026-03-05T14:30:21.877Z
Learning: In BMAD-METHOD, the missing `workflow-config` parameter validation in `tools/cli/installers/lib/ide/templates/combined/antigravity-workflow-yaml.md` (line 11) — no existence check, no extension check, no schema validation before passing the path to workflow.xml — is a pre-existing systemic issue inherited from the corresponding default-*.md template. It is not introduced by PR `#1817`. A future dedicated PR should add pre-invocation validation (file exists, allowed extension such as .yaml/.yml, required top-level keys) across all affected antigravity-*.md and default-*.md templates before any workflow-config path is passed to workflow.xml.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/core/manifest-generator.js:248-265
Timestamp: 2026-03-08T08:10:11.355Z
Learning: In `tools/cli/installers/lib/core/manifest-generator.js`, the `writeFilesManifest()` fallback path (using `this.files` when `installedFiles` is empty) is never reached in production. All real installs supply a comprehensive `installedFiles` array (including skill files) to `generateManifests()`, so the `this.files.push(...)` omission in the skill branch of `getWorkflowsFromPath()` has no practical impact. Do not flag this as a bug in future reviews.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1859
File: tools/cli/installers/lib/core/manifest-generator.js:0-0
Timestamp: 2026-03-08T14:54:51.859Z
Learning: In BMAD-METHOD (`tools/cli/installers/lib/core/manifest-generator.js`), skill `canonicalId` is derived exclusively from the directory name (`path.basename(dir)`), never from the `bmad-skill-manifest.yaml`. If a skill manifest contains a `canonicalId` field, the code emits a `console.warn` and ignores it. Reviewers must not flag the absence of a manifest-provided `canonicalId` for skills, and must not suggest falling back to or synthesizing an ID from any other source.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md:5-5
Timestamp: 2026-03-08T08:10:08.024Z
Learning: In BMAD-METHOD, `./` relative path references in skill step files under `src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/*.md` (and similar skill-format workflow step files) are resolved relative to the skill root directory, not relative to the step file's own directory. For example, `templateFile: './tech-spec-template.md'` in `step-02-plan.md` resolves to `<skill-root>/tech-spec-template.md`, not `<skill-root>/steps/tech-spec-template.md`. This convention is consistent and intentional across all skill-format step files and should not be flagged as ambiguous or fragile.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1834
File: src/bmm/workflows/generate-project-context/bmad-skill-manifest.yaml:1-3
Timestamp: 2026-03-06T22:45:58.474Z
Learning: In BMAD-METHOD, canonicalId uniqueness across bmad-skill-manifest.yaml files is considered enforced by the naming convention (all IDs carry the `bmad-` prefix plus a unique workflow/agent path-derived suffix). Automated duplicate-detection tooling (e.g., in validate-agent-schema.js or CI) is intentionally deferred and should not be flagged in PRs as a blocking concern. The maintainer (alexeyv) considers the convention a sufficient structural safeguard.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1850
File: docs/how-to/quick-fixes.md:41-47
Timestamp: 2026-03-07T23:11:09.292Z
Learning: In BMAD-METHOD, agents and skills have a defined architectural relationship: agents are invoked via their skill entry point. For example, `bmad-quick-flow-solo-dev` is both the agent name and the skill used to invoke it. There is no ambiguity or overlap between "agent skills" and "workflow skills" in docs — reviewers should not flag agent invocations (e.g., `bmad-quick-flow-solo-dev`) as conflicting with standalone workflow skills (e.g., `bmad-quick-spec`). The architecture documentation defines this relationship explicitly.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:32-37
Timestamp: 2026-03-08T13:17:16.398Z
Learning: In BMAD-METHOD, implicit write targets referenced only within checklist steps (e.g., `sprint-status.yaml` in src/bmm/workflows/4-implementation/correct-course/checklist.md) are not declared as explicit path variables in the workflow's Paths section. This is consistent with the convention across all workflows in the project. Reviewers should not flag the absence of such path declarations when the file location is implied by the checklist context.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md:118-118
Timestamp: 2026-03-06T02:01:48.853Z
Learning: In BMAD-METHOD step-04-final-validation.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md), the File Churn Check's RIGHT pattern uses natural language terms such as "distinct files/components" and "consolidation was explicitly considered and rejected with rationale." These terms are intentionally left without formal definitions, numeric overlap thresholds, or required metadata fields. The AI agent executing step-04 runs in the same session as step-02 and step-03 and retains full in-context knowledge of the epic structure; it assesses partial file overlap and component boundaries through contextual judgment. Adding explicit percentage thresholds or structured rationale fields would over-specify the prompt without improving output quality. Reviewers should not flag these terms as ambiguous or request threshold-based or metadata-field additions.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1452
File: src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md:34-46
Timestamp: 2026-01-29T08:53:44.418Z
Learning: In BMAD-METHOD workflow files (under `src/bmm/workflows/`), XML-style tags like `<output-block>`, `<invoke-task>`, etc. are processing markers for AI agents executing workflows, not HTML/XML meant for GitHub markdown rendering. These tags can contain Markdown syntax that will be output/processed by the agent, not rendered by GitHub's sanitizer.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1862
File: src/bmm/workflows/4-implementation/create-story/workflow.md:63-66
Timestamp: 2026-03-08T18:12:34.673Z
Learning: In BMAD-METHOD create-story workflow (src/bmm/workflows/4-implementation/create-story/workflow.md), the `GOTO step 2a` references throughout Step 1 (and corresponding locations at lines 89-97, 159, 216) are pre-existing issues inherited verbatim from the original instructions.xml. The original instructions.xml (commit 09ce855) already had `GOTO step 2a` at lines 24, 50, 55, 117, and 174 but defined only `<step n="2">` — no `<step n="2a">` label existed. This is not a regression introduced by the yaml-to-md conversion PR `#1862`. Reviewers should not flag these GOTO targets as a conversion regression; any fix should be addressed in a dedicated behavioral follow-up PR.
Learnt from: muratkeremozcan
Repo: bmad-code-org/BMAD-METHOD PR: 1367
File: src/bmm/workflows/testarch/test-design/instructions.md:304-307
Timestamp: 2026-01-22T18:34:14.142Z
Learning: When documenting cross-reference patterns in Markdown, ensure header anchors follow GitHub's anchor generation rules: lowercase, spaces to hyphens, remove emojis/special characters, and strip leading/trailing hyphens. Example: '### 🚨 R-001: Title' becomes '#r-001-title'. Use anchors that reflect these rules in documentation across Markdown files.
Comment on lines
+3
to
+6
| **Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling. | ||
| When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff. | ||
| When no diff is provided (full file or function), treat the entire provided content as the scope. | ||
| Ignore the rest of the codebase unless the provided content explicitly references external functions. |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Collaborator
Author
There was a problem hiding this comment.
Dismissed — guard-in-diff scoping is intentional conservative design. The downstream classify step catches false positives, and most guards fall within diff context window.
There was a problem hiding this comment.
@alexeyv, understood — noted that the guard-in-diff constraint is a deliberate conservative scoping choice, with the downstream classify step acting as the false-positive mitigation layer.
ʕ •ᴥ•ʔ 🐇 noted and filed away
✏️ Learnings added
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1871
File: src/core/tasks/bmad-review-edge-case-hunter/workflow.md:3-6
Timestamp: 2026-03-09T14:19:50.698Z
Learning: In BMAD-METHOD `src/core/tasks/bmad-review-edge-case-hunter/workflow.md`, the guard-in-diff scoping rule (requiring guards to appear inside the diff hunks themselves, not in surrounding unchanged context) is intentional conservative design. The downstream classify step is relied upon to filter false positives. Most guards fall within the diff context window in practice. Reviewers should not flag this scoping as overly strict or recommend relaxing it to scan surrounding unchanged lines.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the input-trust guardrail (line 17: "may contain hallucinations, scope creep, or unvalidated assumptions. Follow the workflow exactly...") is intentionally advisory, not a hard enforcement gate. Enforcement is provided by the surrounding workflow structure: the mandatory clarify loop (Step 2 clarify intent), codebase investigation, and the human checkpoint in Step 2. Reviewers should not flag this guardrail as non-operational or require it to include a mandatory verification sub-step.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md:141-149
Timestamp: 2026-03-06T01:57:16.795Z
Learning: In BMAD-METHOD step-02-design-epics.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md), Step C's file overlap review intentionally relies on the agent's contextual judgment rather than a formal file-enumeration procedure. The agent derives file modification lists from the architecture and PRD it used to design the epics, so no explicit enumeration step is needed. Reviewers should not flag the absence of a formal file-sourcing procedure in Step C.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: src/bmm/workflows/4-implementation/create-story/discover-inputs.md:63-67
Timestamp: 2026-03-09T00:01:18.740Z
Learning: In BMAD-METHOD discover-inputs.md (src/bmm/workflows/4-implementation/create-story/discover-inputs.md and src/bmm/workflows/4-implementation/code-review/discover-inputs.md), the whole-document fallback (Step 2b) intentionally loads ALL glob matches into {pattern_name_content} rather than selecting a single canonical file. This is deliberate design — the reporting step (Step 3) and LLM context handling are relied upon to mitigate contradictory sources. Reviewers should not flag the absence of a canonical-match or deduplication rule in the whole-document fallback.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:27-30
Timestamp: 2026-03-08T13:17:16.749Z
Learning: In BMAD-METHOD correct-course workflow (src/bmm/workflows/4-implementation/correct-course/workflow.md), the "DOCUMENT OUTPUT" contract line ("Updated epics, stories, or PRD sections...") is wording carried over verbatim from the original instructions.md during the yaml-to-md format conversion PR `#1858`. It is a pre-existing limitation, not a regression introduced by the conversion. Reviewers should not flag this narrower output contract during format conversion PRs; any expansion of the contract to include Architecture/UI/UX changes and Sprint Change Proposal file should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:60-65
Timestamp: 2026-03-08T17:15:52.768Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the `{{story_path}}` input parameter used in Step 1 ("Use provided {{story_path}} or ask user which story file to review") is not declared in the Input Files table or Configuration Loading section. This is a pre-existing issue inherited from the original instructions.xml, not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag the absence of a formal `{{story_path}}` declaration in conversion PRs; any addition of this parameter to the inputs table should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:154-180
Timestamp: 2026-03-08T17:15:55.392Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the mixed severity terminology — "CRITICAL finding" used in Step 3 execution logic while the categorization action and output template use "HIGH/MEDIUM/LOW" — is a pre-existing inconsistency inherited verbatim from the original instructions.xml. It is not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag this terminology mismatch during format conversion PRs; any normalization of severity levels should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: tools/cli/installers/lib/core/manifest-generator.js:347-354
Timestamp: 2026-03-09T00:01:20.628Z
Learning: In BMAD-METHOD `tools/cli/installers/lib/core/manifest-generator.js`, `getWorkflowsFromPath()` silently skips `workflow.md` files that lack YAML frontmatter (via `continue`). This is intentional: all valid workflow.md files are structurally required to have frontmatter, so files without it are invalid by convention and should be skipped. Reviewers must not flag this silent skip as a missing error or warning — the existing debug log is sufficient and a hard error is not warranted.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:32-37
Timestamp: 2026-03-08T13:17:16.398Z
Learning: In BMAD-METHOD, implicit write targets referenced only within checklist steps (e.g., `sprint-status.yaml` in src/bmm/workflows/4-implementation/correct-course/checklist.md) are not declared as explicit path variables in the workflow's Paths section. This is consistent with the convention across all workflows in the project. Reviewers should not flag the absence of such path declarations when the file location is implied by the checklist context.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:40-47
Timestamp: 2026-03-08T13:17:18.978Z
Learning: In BMAD-METHOD, sharded document inputs (e.g., `*prd*/*.md`, `*epic*/*.md`, `*architecture*/*.md`, `*ux*/*.md`) in workflow input tables are doc-convention glob patterns illustrating the directory structure, not independent behavioral contracts. The actual discovery algorithm for sharded documents always requires an `index.md` entry point within the sharded directory. This is an intentional, project-wide convention used consistently across all workflows. Reviewers should not flag the glob patterns in input tables as mismatched with the index.md-based discovery logic.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1807
File: src/bmm/workflows/bmad-quick-flow/quick-dev2/steps/step-04-review.md:30-30
Timestamp: 2026-03-02T23:53:11.419Z
Learning: In BMAD-METHOD quick-dev2 workflow, one-shot mode relies on session knowledge: the agent executing step-03-implement.md tracks which files it modified in-session, and step-04-review.md invokes `{adversarial_review_task}` with those changed files without constructing a VCS diff. The `baseline_commit` mechanism is only used in plan-code-review mode, not one-shot.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), artifact precedence over prompt text is already established by three layered controls: (1) the ARTIFACT SCAN halt-and-user-choice flow, (2) frozen-after-approval locking, and (3) the input-trust guardrail. No additional explicit precedence rule is needed. Reviewers should not flag the absence of a standalone "artifact state governs routing" precedence declaration.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the phrase "Follow the workflow exactly" in the input-trust guardrail (line 17) is an input-trust directive, not a routing constraint. It does not conflict with, and does not override, the state-aware skip/resume rules in ARTIFACT SCAN (e.g., "skip to step 3" or "skip to step 4" based on artifact status). State-aware routing is part of following the workflow correctly. Reviewers should not flag this phrase as creating a conflict with conditional routing branches.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md:118-118
Timestamp: 2026-03-06T02:01:48.853Z
Learning: In BMAD-METHOD step-04-final-validation.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md), the File Churn Check's RIGHT pattern uses natural language terms such as "distinct files/components" and "consolidation was explicitly considered and rejected with rationale." These terms are intentionally left without formal definitions, numeric overlap thresholds, or required metadata fields. The AI agent executing step-04 runs in the same session as step-02 and step-03 and retains full in-context knowledge of the epic structure; it assesses partial file overlap and component boundaries through contextual judgment. Adding explicit percentage thresholds or structured rationale fields would over-specify the prompt without improving output quality. Reviewers should not flag these terms as ambiguous or request threshold-based or metadata-field additions.
Learnt from: n-zhi
Repo: bmad-code-org/BMAD-METHOD PR: 1817
File: tools/cli/installers/lib/ide/templates/combined/antigravity-agent.md:5-5
Timestamp: 2026-03-05T12:14:43.190Z
Learning: In BMAD-METHOD, the instruction "NEVER break character until given an exit command" in antigravity-agent.md (tools/cli/installers/lib/ide/templates/combined/antigravity-agent.md) is a pre-existing pattern inherited from the corresponding default-*.md template. It is not introduced by PR `#1817`. A future dedicated PR should replace this absolute constraint with a bounded formulation (e.g., "stay in role unless overridden by higher-priority instructions or an exit command") across all affected default-*.md and antigravity-*.md templates.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:26-36
Timestamp: 2026-03-08T13:17:14.385Z
Learning: In BMAD-METHOD workflow.md files (e.g., src/bmm/workflows/4-implementation/correct-course/workflow.md), `{date}` variables used in `default_output_file` path definitions (e.g., `sprint-change-proposal-{date}.md`) are interpreted by LLM agents, not filesystem tooling. The agent generates a filesystem-safe date/time string from the `date` instruction. Flagging this as raw datetime injection producing invalid filenames is a false positive. This is a consistent pattern across all BMAD-METHOD workflows. Reviewers should not flag `{date}` in output file paths as unsafe.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md:121-124
Timestamp: 2026-03-06T02:04:11.275Z
Learning: In BMAD-METHOD step-02-design-epics.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md), the Step A guidance ("outcome is certain", "validated design", "direction changes between epics are unlikely") at lines 121-124 is collaborative facilitation language, not autonomous agent evaluation criteria. The agent surfaces these topics to the user in dialogue; the user asserts design completeness and risk level. Adding operational rubrics, quantified thresholds, or per-artifact checklists to these phrases would contradict the workflow's explicit dialogue-first design (see lines 42-44: "We engage in collaborative dialogue, not command-response"). Reviewers should not flag these phrases as undefined or missing decision logic.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1834
File: src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml:3-3
Timestamp: 2026-03-06T22:45:46.460Z
Learning: In BMAD-METHOD, the `description` field in `bmad-skill-manifest.yaml` files (e.g., `src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml`) follows a concise, action-oriented convention consistent across all manifests in the project. Descriptions like "Perform adversarial code review finding specific issues" are intentionally brief and do not need to enumerate output format details (e.g., severity tags, line-by-line approach). Adding implementation-specific wording such as "line-by-line" would be inaccurate. Reviewers should not flag these descriptions as generic or request additional output/format details.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:18-30
Timestamp: 2026-03-08T13:17:11.250Z
Learning: In BMAD-METHOD, workflow.md files under src/bmm/workflows/ do not validate required config keys (e.g., planning_artifacts, communication_language, document_output_language, user_name) at initialization. The installer guarantees these keys are present in {project-root}/_bmad/bmm/config.yaml before any workflow runs, and downstream HALT conditions (e.g., in Document Discovery and step 1) catch practical failures. Adding per-workflow config validation guards would be inconsistent with all sibling workflows and is not required. Reviewers should not flag the absence of inline config-key validation in these workflow files.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1452
File: src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md:34-46
Timestamp: 2026-01-29T08:53:44.418Z
Learning: In BMAD-METHOD workflow files (under `src/bmm/workflows/`), XML-style tags like `<output-block>`, `<invoke-task>`, etc. are processing markers for AI agents executing workflows, not HTML/XML meant for GitHub markdown rendering. These tags can contain Markdown syntax that will be output/processed by the agent, not rendered by GitHub's sanitizer.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, source skill directories (those collected by the `type: skill` manifest pipeline) never contain a `SKILL.md` file. Therefore, in `installVerbatimSkills` (`tools/cli/installers/lib/ide/_config-driven.js`), writing the generated SKILL.md before calling `fs.copy()` for the directory contents is safe — there is no risk of a source `SKILL.md` overwriting the generated YAML-safe one. Reviewers should not flag this write-before-copy ordering as a bug.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, the `installVerbatimSkills` method in `tools/cli/installers/lib/ide/_config-driven.js` hardcodes `workflow.md` as the skill entry file in the generated SKILL.md launcher intentionally. The `type: skill` manifest pipeline guarantees that `workflow.md` is always the canonical entry file for verbatim skill directories; no other entry file names (e.g., `workflow.yaml`, `workflow-*.md`) are possible. Reviewers should not flag this hardcoded reference as a bug or suggest dynamic entry-file detection.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1850
File: docs/how-to/quick-fixes.md:41-47
Timestamp: 2026-03-07T23:11:09.292Z
Learning: In BMAD-METHOD, agents and skills have a defined architectural relationship: agents are invoked via their skill entry point. For example, `bmad-quick-flow-solo-dev` is both the agent name and the skill used to invoke it. There is no ambiguity or overlap between "agent skills" and "workflow skills" in docs — reviewers should not flag agent invocations (e.g., `bmad-quick-flow-solo-dev`) as conflicting with standalone workflow skills (e.g., `bmad-quick-spec`). The architecture documentation defines this relationship explicitly.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md:5-5
Timestamp: 2026-03-08T08:10:08.024Z
Learning: In BMAD-METHOD, `./` relative path references in skill step files under `src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/*.md` (and similar skill-format workflow step files) are resolved relative to the skill root directory, not relative to the step file's own directory. For example, `templateFile: './tech-spec-template.md'` in `step-02-plan.md` resolves to `<skill-root>/tech-spec-template.md`, not `<skill-root>/steps/tech-spec-template.md`. This convention is consistent and intentional across all skill-format step files and should not be flagged as ambiguous or fragile.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/core/manifest-generator.js:248-265
Timestamp: 2026-03-08T08:10:11.355Z
Learning: In `tools/cli/installers/lib/core/manifest-generator.js`, the `writeFilesManifest()` fallback path (using `this.files` when `installedFiles` is empty) is never reached in production. All real installs supply a comprehensive `installedFiles` array (including skill files) to `generateManifests()`, so the `this.files.push(...)` omission in the skill branch of `getWorkflowsFromPath()` has no practical impact. Do not flag this as a bug in future reviews.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1862
File: src/bmm/workflows/4-implementation/create-story/workflow.md:63-66
Timestamp: 2026-03-08T18:12:34.673Z
Learning: In BMAD-METHOD create-story workflow (src/bmm/workflows/4-implementation/create-story/workflow.md), the `GOTO step 2a` references throughout Step 1 (and corresponding locations at lines 89-97, 159, 216) are pre-existing issues inherited verbatim from the original instructions.xml. The original instructions.xml (commit 09ce855) already had `GOTO step 2a` at lines 24, 50, 55, 117, and 174 but defined only `<step n="2">` — no `<step n="2a">` label existed. This is not a regression introduced by the yaml-to-md conversion PR `#1862`. Reviewers should not flag these GOTO targets as a conversion regression; any fix should be addressed in a dedicated behavioral follow-up PR.
Learnt from: muratkeremozcan
Repo: bmad-code-org/BMAD-METHOD PR: 1367
File: src/bmm/workflows/testarch/test-design/instructions.md:304-307
Timestamp: 2026-01-22T18:34:14.142Z
Learning: When documenting cross-reference patterns in Markdown, ensure header anchors follow GitHub's anchor generation rules: lowercase, spaces to hyphens, remove emojis/special characters, and strip leading/trailing hyphens. Example: '### 🚨 R-001: Title' becomes '#r-001-title'. Use anchors that reflect these rules in documentation across Markdown files.
Comment on lines
+4
to
+6
| When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff. | ||
| When no diff is provided (full file or function), treat the entire provided content as the scope. | ||
| Ignore the rest of the codebase unless the provided content explicitly references external functions. |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Collaborator
Author
There was a problem hiding this comment.
Dismissed — deleted guards are already covered by "scan diff hunks" and "lack an explicit guard in the diff." Minus lines are part of diff hunks by definition.
There was a problem hiding this comment.
@alexeyv — fair point. Minus lines are structurally part of any unified diff hunk, so a deleted guard is visible to the scanner in the same pass, and the absence of that guard in the resulting content satisfies the "lack an explicit guard in the diff" condition. The concern doesn't apply here. Acknowledged.
🧠 Learnings used
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the input-trust guardrail (line 17: "may contain hallucinations, scope creep, or unvalidated assumptions. Follow the workflow exactly...") is intentionally advisory, not a hard enforcement gate. Enforcement is provided by the surrounding workflow structure: the mandatory clarify loop (Step 2 clarify intent), codebase investigation, and the human checkpoint in Step 2. Reviewers should not flag this guardrail as non-operational or require it to include a mandatory verification sub-step.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md:141-149
Timestamp: 2026-03-06T01:57:16.795Z
Learning: In BMAD-METHOD step-02-design-epics.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md), Step C's file overlap review intentionally relies on the agent's contextual judgment rather than a formal file-enumeration procedure. The agent derives file modification lists from the architecture and PRD it used to design the epics, so no explicit enumeration step is needed. Reviewers should not flag the absence of a formal file-sourcing procedure in Step C.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: src/bmm/workflows/4-implementation/create-story/discover-inputs.md:63-67
Timestamp: 2026-03-09T00:01:18.740Z
Learning: In BMAD-METHOD discover-inputs.md (src/bmm/workflows/4-implementation/create-story/discover-inputs.md and src/bmm/workflows/4-implementation/code-review/discover-inputs.md), the whole-document fallback (Step 2b) intentionally loads ALL glob matches into {pattern_name_content} rather than selecting a single canonical file. This is deliberate design — the reporting step (Step 3) and LLM context handling are relied upon to mitigate contradictory sources. Reviewers should not flag the absence of a canonical-match or deduplication rule in the whole-document fallback.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:27-30
Timestamp: 2026-03-08T13:17:16.749Z
Learning: In BMAD-METHOD correct-course workflow (src/bmm/workflows/4-implementation/correct-course/workflow.md), the "DOCUMENT OUTPUT" contract line ("Updated epics, stories, or PRD sections...") is wording carried over verbatim from the original instructions.md during the yaml-to-md format conversion PR `#1858`. It is a pre-existing limitation, not a regression introduced by the conversion. Reviewers should not flag this narrower output contract during format conversion PRs; any expansion of the contract to include Architecture/UI/UX changes and Sprint Change Proposal file should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:60-65
Timestamp: 2026-03-08T17:15:52.768Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the `{{story_path}}` input parameter used in Step 1 ("Use provided {{story_path}} or ask user which story file to review") is not declared in the Input Files table or Configuration Loading section. This is a pre-existing issue inherited from the original instructions.xml, not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag the absence of a formal `{{story_path}}` declaration in conversion PRs; any addition of this parameter to the inputs table should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:154-180
Timestamp: 2026-03-08T17:15:55.392Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the mixed severity terminology — "CRITICAL finding" used in Step 3 execution logic while the categorization action and output template use "HIGH/MEDIUM/LOW" — is a pre-existing inconsistency inherited verbatim from the original instructions.xml. It is not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag this terminology mismatch during format conversion PRs; any normalization of severity levels should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: tools/cli/installers/lib/core/manifest-generator.js:347-354
Timestamp: 2026-03-09T00:01:20.628Z
Learning: In BMAD-METHOD `tools/cli/installers/lib/core/manifest-generator.js`, `getWorkflowsFromPath()` silently skips `workflow.md` files that lack YAML frontmatter (via `continue`). This is intentional: all valid workflow.md files are structurally required to have frontmatter, so files without it are invalid by convention and should be skipped. Reviewers must not flag this silent skip as a missing error or warning — the existing debug log is sufficient and a hard error is not warranted.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:32-37
Timestamp: 2026-03-08T13:17:16.398Z
Learning: In BMAD-METHOD, implicit write targets referenced only within checklist steps (e.g., `sprint-status.yaml` in src/bmm/workflows/4-implementation/correct-course/checklist.md) are not declared as explicit path variables in the workflow's Paths section. This is consistent with the convention across all workflows in the project. Reviewers should not flag the absence of such path declarations when the file location is implied by the checklist context.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:40-47
Timestamp: 2026-03-08T13:17:18.978Z
Learning: In BMAD-METHOD, sharded document inputs (e.g., `*prd*/*.md`, `*epic*/*.md`, `*architecture*/*.md`, `*ux*/*.md`) in workflow input tables are doc-convention glob patterns illustrating the directory structure, not independent behavioral contracts. The actual discovery algorithm for sharded documents always requires an `index.md` entry point within the sharded directory. This is an intentional, project-wide convention used consistently across all workflows. Reviewers should not flag the glob patterns in input tables as mismatched with the index.md-based discovery logic.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1807
File: src/bmm/workflows/bmad-quick-flow/quick-dev2/steps/step-04-review.md:30-30
Timestamp: 2026-03-02T23:53:11.419Z
Learning: In BMAD-METHOD quick-dev2 workflow, one-shot mode relies on session knowledge: the agent executing step-03-implement.md tracks which files it modified in-session, and step-04-review.md invokes `{adversarial_review_task}` with those changed files without constructing a VCS diff. The `baseline_commit` mechanism is only used in plan-code-review mode, not one-shot.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md:118-118
Timestamp: 2026-03-06T02:01:48.853Z
Learning: In BMAD-METHOD step-04-final-validation.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md), the File Churn Check's RIGHT pattern uses natural language terms such as "distinct files/components" and "consolidation was explicitly considered and rejected with rationale." These terms are intentionally left without formal definitions, numeric overlap thresholds, or required metadata fields. The AI agent executing step-04 runs in the same session as step-02 and step-03 and retains full in-context knowledge of the epic structure; it assesses partial file overlap and component boundaries through contextual judgment. Adding explicit percentage thresholds or structured rationale fields would over-specify the prompt without improving output quality. Reviewers should not flag these terms as ambiguous or request threshold-based or metadata-field additions.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), artifact precedence over prompt text is already established by three layered controls: (1) the ARTIFACT SCAN halt-and-user-choice flow, (2) frozen-after-approval locking, and (3) the input-trust guardrail. No additional explicit precedence rule is needed. Reviewers should not flag the absence of a standalone "artifact state governs routing" precedence declaration.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the phrase "Follow the workflow exactly" in the input-trust guardrail (line 17) is an input-trust directive, not a routing constraint. It does not conflict with, and does not override, the state-aware skip/resume rules in ARTIFACT SCAN (e.g., "skip to step 3" or "skip to step 4" based on artifact status). State-aware routing is part of following the workflow correctly. Reviewers should not flag this phrase as creating a conflict with conditional routing branches.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1834
File: src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml:3-3
Timestamp: 2026-03-06T22:45:46.460Z
Learning: In BMAD-METHOD, the `description` field in `bmad-skill-manifest.yaml` files (e.g., `src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml`) follows a concise, action-oriented convention consistent across all manifests in the project. Descriptions like "Perform adversarial code review finding specific issues" are intentionally brief and do not need to enumerate output format details (e.g., severity tags, line-by-line approach). Adding implementation-specific wording such as "line-by-line" would be inaccurate. Reviewers should not flag these descriptions as generic or request additional output/format details.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:18-30
Timestamp: 2026-03-08T13:17:11.250Z
Learning: In BMAD-METHOD, workflow.md files under src/bmm/workflows/ do not validate required config keys (e.g., planning_artifacts, communication_language, document_output_language, user_name) at initialization. The installer guarantees these keys are present in {project-root}/_bmad/bmm/config.yaml before any workflow runs, and downstream HALT conditions (e.g., in Document Discovery and step 1) catch practical failures. Adding per-workflow config validation guards would be inconsistent with all sibling workflows and is not required. Reviewers should not flag the absence of inline config-key validation in these workflow files.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1452
File: src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md:34-46
Timestamp: 2026-01-29T08:53:44.418Z
Learning: In BMAD-METHOD workflow files (under `src/bmm/workflows/`), XML-style tags like `<output-block>`, `<invoke-task>`, etc. are processing markers for AI agents executing workflows, not HTML/XML meant for GitHub markdown rendering. These tags can contain Markdown syntax that will be output/processed by the agent, not rendered by GitHub's sanitizer.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, source skill directories (those collected by the `type: skill` manifest pipeline) never contain a `SKILL.md` file. Therefore, in `installVerbatimSkills` (`tools/cli/installers/lib/ide/_config-driven.js`), writing the generated SKILL.md before calling `fs.copy()` for the directory contents is safe — there is no risk of a source `SKILL.md` overwriting the generated YAML-safe one. Reviewers should not flag this write-before-copy ordering as a bug.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, the `installVerbatimSkills` method in `tools/cli/installers/lib/ide/_config-driven.js` hardcodes `workflow.md` as the skill entry file in the generated SKILL.md launcher intentionally. The `type: skill` manifest pipeline guarantees that `workflow.md` is always the canonical entry file for verbatim skill directories; no other entry file names (e.g., `workflow.yaml`, `workflow-*.md`) are possible. Reviewers should not flag this hardcoded reference as a bug or suggest dynamic entry-file detection.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1850
File: docs/how-to/quick-fixes.md:41-47
Timestamp: 2026-03-07T23:11:09.292Z
Learning: In BMAD-METHOD, agents and skills have a defined architectural relationship: agents are invoked via their skill entry point. For example, `bmad-quick-flow-solo-dev` is both the agent name and the skill used to invoke it. There is no ambiguity or overlap between "agent skills" and "workflow skills" in docs — reviewers should not flag agent invocations (e.g., `bmad-quick-flow-solo-dev`) as conflicting with standalone workflow skills (e.g., `bmad-quick-spec`). The architecture documentation defines this relationship explicitly.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md:5-5
Timestamp: 2026-03-08T08:10:08.024Z
Learning: In BMAD-METHOD, `./` relative path references in skill step files under `src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/*.md` (and similar skill-format workflow step files) are resolved relative to the skill root directory, not relative to the step file's own directory. For example, `templateFile: './tech-spec-template.md'` in `step-02-plan.md` resolves to `<skill-root>/tech-spec-template.md`, not `<skill-root>/steps/tech-spec-template.md`. This convention is consistent and intentional across all skill-format step files and should not be flagged as ambiguous or fragile.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/core/manifest-generator.js:248-265
Timestamp: 2026-03-08T08:10:11.355Z
Learning: In `tools/cli/installers/lib/core/manifest-generator.js`, the `writeFilesManifest()` fallback path (using `this.files` when `installedFiles` is empty) is never reached in production. All real installs supply a comprehensive `installedFiles` array (including skill files) to `generateManifests()`, so the `this.files.push(...)` omission in the skill branch of `getWorkflowsFromPath()` has no practical impact. Do not flag this as a bug in future reviews.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1862
File: src/bmm/workflows/4-implementation/create-story/workflow.md:63-66
Timestamp: 2026-03-08T18:12:34.673Z
Learning: In BMAD-METHOD create-story workflow (src/bmm/workflows/4-implementation/create-story/workflow.md), the `GOTO step 2a` references throughout Step 1 (and corresponding locations at lines 89-97, 159, 216) are pre-existing issues inherited verbatim from the original instructions.xml. The original instructions.xml (commit 09ce855) already had `GOTO step 2a` at lines 24, 50, 55, 117, and 174 but defined only `<step n="2">` — no `<step n="2a">` label existed. This is not a regression introduced by the yaml-to-md conversion PR `#1862`. Reviewers should not flag these GOTO targets as a conversion regression; any fix should be addressed in a dedicated behavioral follow-up PR.
Learnt from: muratkeremozcan
Repo: bmad-code-org/BMAD-METHOD PR: 1367
File: src/bmm/workflows/testarch/test-design/instructions.md:304-307
Timestamp: 2026-01-22T18:34:14.142Z
Learning: When documenting cross-reference patterns in Markdown, ensure header anchors follow GitHub's anchor generation rules: lowercase, spaces to hyphens, remove emojis/special characters, and strip leading/trailing hyphens. Example: '### 🚨 R-001: Title' becomes '#r-001-title'. Use anchors that reflect these rules in documentation across Markdown files.
Comment on lines
+29
to
+30
| - If `also_consider` input was provided, incorporate those areas into the analysis | ||
| - Enumerate all branching paths and boundary conditions within scope: conditionals, switches, early returns, guard clauses, loops, error handlers, null/empty states, overflow, type edges, concurrency, timing |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Collaborator
Author
There was a problem hiding this comment.
Rejected — also_consider is a focus-area hint, not a scope modifier. No ambiguity with diff mode scope rules.
There was a problem hiding this comment.
@alexeyv, understood — also_consider is a focus-area hint that influences analysis emphasis within the already-established scope, not a scope expander. I'll defer to your judgment here.
✏️ Learnings added
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1871
File: src/core/tasks/bmad-review-edge-case-hunter/workflow.md:0-0
Timestamp: 2026-03-09T14:19:51.521Z
Learning: In BMAD-METHOD edge-case-hunter skill (src/core/tasks/bmad-review-edge-case-hunter/workflow.md), the `also_consider` input is a focus-area hint that influences analysis emphasis within the already-established scope (diff hunks or full file/function). It is NOT a scope modifier and cannot expand the analysis beyond the diff in diff mode. Reviewers should not flag `also_consider` as creating scope ambiguity with diff-mode scanning rules.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: src/bmm/workflows/4-implementation/create-story/discover-inputs.md:63-67
Timestamp: 2026-03-09T00:01:18.740Z
Learning: In BMAD-METHOD discover-inputs.md (src/bmm/workflows/4-implementation/create-story/discover-inputs.md and src/bmm/workflows/4-implementation/code-review/discover-inputs.md), the whole-document fallback (Step 2b) intentionally loads ALL glob matches into {pattern_name_content} rather than selecting a single canonical file. This is deliberate design — the reporting step (Step 3) and LLM context handling are relied upon to mitigate contradictory sources. Reviewers should not flag the absence of a canonical-match or deduplication rule in the whole-document fallback.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md:141-149
Timestamp: 2026-03-06T01:57:16.795Z
Learning: In BMAD-METHOD step-02-design-epics.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md), Step C's file overlap review intentionally relies on the agent's contextual judgment rather than a formal file-enumeration procedure. The agent derives file modification lists from the architecture and PRD it used to design the epics, so no explicit enumeration step is needed. Reviewers should not flag the absence of a formal file-sourcing procedure in Step C.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the input-trust guardrail (line 17: "may contain hallucinations, scope creep, or unvalidated assumptions. Follow the workflow exactly...") is intentionally advisory, not a hard enforcement gate. Enforcement is provided by the surrounding workflow structure: the mandatory clarify loop (Step 2 clarify intent), codebase investigation, and the human checkpoint in Step 2. Reviewers should not flag this guardrail as non-operational or require it to include a mandatory verification sub-step.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1864
File: tools/cli/installers/lib/core/manifest-generator.js:347-354
Timestamp: 2026-03-09T00:01:20.628Z
Learning: In BMAD-METHOD `tools/cli/installers/lib/core/manifest-generator.js`, `getWorkflowsFromPath()` silently skips `workflow.md` files that lack YAML frontmatter (via `continue`). This is intentional: all valid workflow.md files are structurally required to have frontmatter, so files without it are invalid by convention and should be skipped. Reviewers must not flag this silent skip as a missing error or warning — the existing debug log is sufficient and a hard error is not warranted.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:40-47
Timestamp: 2026-03-08T13:17:18.978Z
Learning: In BMAD-METHOD, sharded document inputs (e.g., `*prd*/*.md`, `*epic*/*.md`, `*architecture*/*.md`, `*ux*/*.md`) in workflow input tables are doc-convention glob patterns illustrating the directory structure, not independent behavioral contracts. The actual discovery algorithm for sharded documents always requires an `index.md` entry point within the sharded directory. This is an intentional, project-wide convention used consistently across all workflows. Reviewers should not flag the glob patterns in input tables as mismatched with the index.md-based discovery logic.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:154-180
Timestamp: 2026-03-08T17:15:55.392Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the mixed severity terminology — "CRITICAL finding" used in Step 3 execution logic while the categorization action and output template use "HIGH/MEDIUM/LOW" — is a pre-existing inconsistency inherited verbatim from the original instructions.xml. It is not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag this terminology mismatch during format conversion PRs; any normalization of severity levels should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:27-30
Timestamp: 2026-03-08T13:17:16.749Z
Learning: In BMAD-METHOD correct-course workflow (src/bmm/workflows/4-implementation/correct-course/workflow.md), the "DOCUMENT OUTPUT" contract line ("Updated epics, stories, or PRD sections...") is wording carried over verbatim from the original instructions.md during the yaml-to-md format conversion PR `#1858`. It is a pre-existing limitation, not a regression introduced by the conversion. Reviewers should not flag this narrower output contract during format conversion PRs; any expansion of the contract to include Architecture/UI/UX changes and Sprint Change Proposal file should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:60-65
Timestamp: 2026-03-08T17:15:52.768Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the `{{story_path}}` input parameter used in Step 1 ("Use provided {{story_path}} or ask user which story file to review") is not declared in the Input Files table or Configuration Loading section. This is a pre-existing issue inherited from the original instructions.xml, not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag the absence of a formal `{{story_path}}` declaration in conversion PRs; any addition of this parameter to the inputs table should be addressed in a dedicated behavioral follow-up PR.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1834
File: src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml:3-3
Timestamp: 2026-03-06T22:45:46.460Z
Learning: In BMAD-METHOD, the `description` field in `bmad-skill-manifest.yaml` files (e.g., `src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml`) follows a concise, action-oriented convention consistent across all manifests in the project. Descriptions like "Perform adversarial code review finding specific issues" are intentionally brief and do not need to enumerate output format details (e.g., severity tags, line-by-line approach). Adding implementation-specific wording such as "line-by-line" would be inaccurate. Reviewers should not flag these descriptions as generic or request additional output/format details.
Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md:118-118
Timestamp: 2026-03-06T02:01:48.853Z
Learning: In BMAD-METHOD step-04-final-validation.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md), the File Churn Check's RIGHT pattern uses natural language terms such as "distinct files/components" and "consolidation was explicitly considered and rejected with rationale." These terms are intentionally left without formal definitions, numeric overlap thresholds, or required metadata fields. The AI agent executing step-04 runs in the same session as step-02 and step-03 and retains full in-context knowledge of the epic structure; it assesses partial file overlap and component boundaries through contextual judgment. Adding explicit percentage thresholds or structured rationale fields would over-specify the prompt without improving output quality. Reviewers should not flag these terms as ambiguous or request threshold-based or metadata-field additions.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), artifact precedence over prompt text is already established by three layered controls: (1) the ARTIFACT SCAN halt-and-user-choice flow, (2) frozen-after-approval locking, and (3) the input-trust guardrail. No additional explicit precedence rule is needed. Reviewers should not flag the absence of a standalone "artifact state governs routing" precedence declaration.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1825
File: src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md:17-17
Timestamp: 2026-03-06T22:18:19.515Z
Learning: In BMAD-METHOD quick-dev-new-preview step-01-clarify-and-route.md (src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md), the phrase "Follow the workflow exactly" in the input-trust guardrail (line 17) is an input-trust directive, not a routing constraint. It does not conflict with, and does not override, the state-aware skip/resume rules in ARTIFACT SCAN (e.g., "skip to step 3" or "skip to step 4" based on artifact status). State-aware routing is part of following the workflow correctly. Reviewers should not flag this phrase as creating a conflict with conditional routing branches.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1858
File: src/bmm/workflows/4-implementation/correct-course/workflow.md:18-30
Timestamp: 2026-03-08T13:17:11.250Z
Learning: In BMAD-METHOD, workflow.md files under src/bmm/workflows/ do not validate required config keys (e.g., planning_artifacts, communication_language, document_output_language, user_name) at initialization. The installer guarantees these keys are present in {project-root}/_bmad/bmm/config.yaml before any workflow runs, and downstream HALT conditions (e.g., in Document Discovery and step 1) catch practical failures. Adding per-workflow config validation guards would be inconsistent with all sibling workflows and is not required. Reviewers should not flag the absence of inline config-key validation in these workflow files.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1452
File: src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md:34-46
Timestamp: 2026-01-29T08:53:44.418Z
Learning: In BMAD-METHOD workflow files (under `src/bmm/workflows/`), XML-style tags like `<output-block>`, `<invoke-task>`, etc. are processing markers for AI agents executing workflows, not HTML/XML meant for GitHub markdown rendering. These tags can contain Markdown syntax that will be output/processed by the agent, not rendered by GitHub's sanitizer.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, source skill directories (those collected by the `type: skill` manifest pipeline) never contain a `SKILL.md` file. Therefore, in `installVerbatimSkills` (`tools/cli/installers/lib/ide/_config-driven.js`), writing the generated SKILL.md before calling `fs.copy()` for the directory contents is safe — there is no risk of a source `SKILL.md` overwriting the generated YAML-safe one. Reviewers should not flag this write-before-copy ordering as a bug.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/ide/_config-driven.js:688-700
Timestamp: 2026-03-08T08:10:23.919Z
Learning: In BMAD-METHOD, the `installVerbatimSkills` method in `tools/cli/installers/lib/ide/_config-driven.js` hardcodes `workflow.md` as the skill entry file in the generated SKILL.md launcher intentionally. The `type: skill` manifest pipeline guarantees that `workflow.md` is always the canonical entry file for verbatim skill directories; no other entry file names (e.g., `workflow.yaml`, `workflow-*.md`) are possible. Reviewers should not flag this hardcoded reference as a bug or suggest dynamic entry-file detection.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1850
File: docs/how-to/quick-fixes.md:41-47
Timestamp: 2026-03-07T23:11:09.292Z
Learning: In BMAD-METHOD, agents and skills have a defined architectural relationship: agents are invoked via their skill entry point. For example, `bmad-quick-flow-solo-dev` is both the agent name and the skill used to invoke it. There is no ambiguity or overlap between "agent skills" and "workflow skills" in docs — reviewers should not flag agent invocations (e.g., `bmad-quick-flow-solo-dev`) as conflicting with standalone workflow skills (e.g., `bmad-quick-spec`). The architecture documentation defines this relationship explicitly.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md:5-5
Timestamp: 2026-03-08T08:10:08.024Z
Learning: In BMAD-METHOD, `./` relative path references in skill step files under `src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/*.md` (and similar skill-format workflow step files) are resolved relative to the skill root directory, not relative to the step file's own directory. For example, `templateFile: './tech-spec-template.md'` in `step-02-plan.md` resolves to `<skill-root>/tech-spec-template.md`, not `<skill-root>/steps/tech-spec-template.md`. This convention is consistent and intentional across all skill-format step files and should not be flagged as ambiguous or fragile.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1851
File: tools/cli/installers/lib/core/manifest-generator.js:248-265
Timestamp: 2026-03-08T08:10:11.355Z
Learning: In `tools/cli/installers/lib/core/manifest-generator.js`, the `writeFilesManifest()` fallback path (using `this.files` when `installedFiles` is empty) is never reached in production. All real installs supply a comprehensive `installedFiles` array (including skill files) to `generateManifests()`, so the `this.files.push(...)` omission in the skill branch of `getWorkflowsFromPath()` has no practical impact. Do not flag this as a bug in future reviews.
Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1862
File: src/bmm/workflows/4-implementation/create-story/workflow.md:63-66
Timestamp: 2026-03-08T18:12:34.673Z
Learning: In BMAD-METHOD create-story workflow (src/bmm/workflows/4-implementation/create-story/workflow.md), the `GOTO step 2a` references throughout Step 1 (and corresponding locations at lines 89-97, 159, 216) are pre-existing issues inherited verbatim from the original instructions.xml. The original instructions.xml (commit 09ce855) already had `GOTO step 2a` at lines 24, 50, 55, 117, and 174 but defined only `<step n="2">` — no `<step n="2a">` label existed. This is not a regression introduced by the yaml-to-md conversion PR `#1862`. Reviewers should not flag these GOTO targets as a conversion regression; any fix should be addressed in a dedicated behavioral follow-up PR.
Learnt from: muratkeremozcan
Repo: bmad-code-org/BMAD-METHOD PR: 1367
File: src/bmm/workflows/testarch/test-design/instructions.md:304-307
Timestamp: 2026-01-22T18:34:14.142Z
Learning: When documenting cross-reference patterns in Markdown, ensure header anchors follow GitHub's anchor generation rules: lowercase, spaces to hyphens, remove emojis/special characters, and strip leading/trailing hyphens. Example: '### 🚨 R-001: Title' becomes '#r-001-title'. Use anchors that reflect these rules in documentation across Markdown files.
- Fix "task returns" → "skill returns" terminology in review-pr instructions - Remove edge-case-hunter entry from central manifest (has own directory manifest) - Add sentinel error response for empty/bad input instead of silent empty array - Reframe Step 2 with two-lens approach: control flow paths + domain boundaries - Simplify Step 3 to reference Step 2 edge classes instead of duplicating list Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This was referenced Mar 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
review-edge-case-hunter.xmlwith native skill directory (SKILL.md+workflow.md+bmad-skill-manifest.yaml), following the pattern frombmad-review-adversarial-generalTest plan
review-edge-case-hunter.xmlno longer exists in reporeview-edge-case-hunter.xml— zero matches expected🤖 Generated with Claude Code