Skip to content

feat(skills): add discovery rigor and workflow contract support#2237

Closed
edamlmmv wants to merge 2 commits intobmad-code-org:mainfrom
edamlmmv:feat/discovery-rigor-workflow-contract
Closed

feat(skills): add discovery rigor and workflow contract support#2237
edamlmmv wants to merge 2 commits intobmad-code-org:mainfrom
edamlmmv:feat/discovery-rigor-workflow-contract

Conversation

@edamlmmv
Copy link
Copy Markdown

What

Adds a discovery-rigor core skill and a workflow-contract skill, plus supporting memory-manager and guidance updates so BMAD workflows can start from explicit discovery state and carry cleaner handoffs.

Why

Recent workflow changes needed a more structured discovery entry point, clearer contract authoring guidance, and validation behavior that matches current skill packaging. This keeps the skill surface more consistent and recovery-friendly for contributors and downstream agents.

How

  • add discovery-rigor, workflow-contract, and memory-manager skill packages with manifests, steps, and supporting resources
  • update help, distillator, review, and dev-story guidance to use the new stop-gates and recovery rules
  • harden manifest and reference validation, and add installation tests for stale-agent pruning and nested helper SKILL scanning

Testing

Ran npm run quality successfully.

- add discovery rigor and memory manager skill flows plus supporting resources

- add workflow contract skill scaffolding and update related module metadata

- tighten validation, installation coverage, and local ignore rules for contribution hygiene
@edamlmmv edamlmmv closed this Apr 10, 2026
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 10, 2026

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This pull request introduces a comprehensive workflow-contract creation skill, an extensive discovery-rigor framework with specialized agents and domain resources, a new memory-manager skill for state persistence, and refactors skill/agent manifest discovery to prevent nested traversal. Additionally, it enhances story templates with Exit Criteria and Rollback Boundary sections, updates dev-story and code-review workflows to enforce immutability of frozen content, and refines the distillator and adversarial-review skills.

Changes

Cohort / File(s) Summary
Configuration & Linting
.gitignore, .markdownlint-cli2.yaml
Added .history/ directory exclusions to both version control and linting configuration.
Story Template & Exit Criteria
src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/steps/step-03-create-stories.md, src/bmm-skills/4-implementation/bmad-create-story/template.md
Extended story requirements with new Exit Criteria and Rollback Boundary fields; wrapped story content in <frozen-after-approval> block; reorganized template sections (Implementation Plan, Debug Log, Completion Notes, File List, Change Log).
Dev Story Workflow
src/bmm-skills/4-implementation/bmad-dev-story/workflow.md, src/bmm-skills/4-implementation/bmad-dev-story/checklist.md
Refactored workflow to enforce immutability of frozen sections (Story statement, Acceptance/Exit Criteria, Rollback Boundary); added explicit halts when frozen content cannot be satisfied; broadened review-follow-ups scope from marker-based to all unresolved findings; enhanced task completion and review continuation detection logic.
Code Review Presentation
src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md
Added explicit "Deferred-item triage guidance" criteria defining when findings should/should not be deferred, with exclusions for introduced changes, acceptance-criterion blockers, and security vulnerabilities.
Workflow Contract Skill
src/bmm-skills/3-solutioning/bmad-create-workflow-contract/*
Added complete new skill with three-step workflow: init (recovery, discovery, systems mapping, mode selection), define (surface discovery/triage, contract drafting, cross-contract consistency), and finalize (completeness verification, optional adversarial review, handoff).
Discovery Rigor Skill
src/core-skills/bmad-discovery-rigor/SKILL.md, src/core-skills/bmad-discovery-rigor/workflow.md, src/core-skills/bmad-discovery-rigor/steps/*
Added comprehensive discovery-rigor skill with five-step workflow (classify, quick-handoff, interview, blind-spots, research, handoff), State Ledger maintenance, recovery protocol, autonomous mode behavior, and conditional branching based on activity/tier/convergence.
Discovery Rigor Agent & Resources
src/core-skills/bmad-discovery-rigor/agents/SKILL.md, src/core-skills/bmad-discovery-rigor/agents/bmad-skill-manifest.yaml, src/core-skills/bmad-discovery-rigor/resources/*
Added thinking-protocol agent with stop-gate sequence and State Ledger verification; added domain resources for software engineering, LLM systems, formal readiness, and structured reasoning with probe questions and risk patterns.
Memory Manager Skill
src/core-skills/bmad-memory-manager/*
Added new skill providing deterministic persist/recover/list/clear operations for BMAD workflow state, with session and workspace storage scopes, provenance tracking, and ops-log audit trail.
Distillator Enhancements
src/core-skills/bmad-distillator/SKILL.md, src/core-skills/bmad-distillator/agents/distillate-compressor.md, src/core-skills/bmad-distillator/agents/round-trip-reconstructor.md, src/core-skills/bmad-distillator/resources/*
Extended distillator with session-trace/calibration mode, coverage-manifest tracking, graceful degradation for split-distillate validation, and session-trace template preservation; updated format examples with formatting improvements.
Adversarial Review Enhancement
src/core-skills/bmad-review-adversarial-general/SKILL.md
Added COMPLETENESS REVIEW MODE that traces specification requirements against implementation (Met/Partial/Missing/Contradicted), detects scope creep, and reports comprehensive findings before standard adversarial analysis.
Help Skill Updates
src/core-skills/bmad-help/SKILL.md
Tightened quick-start behavior to require explicit State Ledger handoff or single next step; added Discovery-Rigor and State Ledger awareness gates with detection rules and skip criteria; enhanced module-disambiguation logic.
Manifest Generation & Skill Discovery
tools/installer/core/manifest-generator.js, tools/validate-skills.js, tools/validate-file-refs.js
Modified collectSkills() to stop descending after finding SKILL.md; changed writeAgentManifest() to treat scanned agents as authoritative (no legacy merging) and output deterministically; updated skill validator to filter agent directories; enhanced file-ref validation to skip external/provenance references.
Manifest Files & Tests
src/bmm-skills/.../bmad-skill-manifest.yaml, src/core-skills/.../bmad-skill-manifest.yaml, test/test-installation-components.js
Added type: skill manifest files throughout skill structure; added test suites 35–36 validating agent-manifest regeneration and nested SKILL.md handling; cleaned up agent manifest on rebuild.

Sequence Diagram(s)

sequenceDiagram
    participant User as User/Context
    participant Step1 as Step 1: Classify
    participant Step2 as Step 2: Interview
    participant Step3 as Step 3: Blind-Spots
    participant Step4 as Step 4: Research
    participant Step5 as Step 5: Handoff
    participant StateLedger as State Ledger

    User->>Step1: Start Discovery Rigor
    Step1->>Step1: Load classification guide
    Step1->>User: Ask: Activity/Tier/Convergence
    User-->>Step1: Provide classification
    Step1->>StateLedger: Record classification
    alt Activity=Solve & Tier=Quick
        Step1->>Step1: Route to Quick Handoff
    else Other paths
        Step1->>Step2: Route to Interview
    end

    Step2->>Step2: Load domain fragments
    Step2->>User: Ask 3-6 decision questions (2-3 batches)
    User-->>Step2: Provide responses
    Step2->>StateLedger: Update with findings/counter
    Step2->>Step3: Route to Blind-Spots

    Step3->>Step3: Load system reality categories
    Step3->>User: Identify blind-spots per category (≤5 at a time)
    User-->>Step3: Triage blind-spots
    Step3->>StateLedger: Record blind-spots/counter
    alt Counter ≥2 or convergence evidence gap
        Step3->>Step4: Route to Research
    else Sufficient depth
        Step3->>Step5: Route to Handoff
    end

    Step4->>Step4: Build research plan from gaps
    Step4->>User: Investigate gaps / confirm resolution
    User-->>Step4: Provide evidence/confirm
    Step4->>StateLedger: Reset counter, record research
    Step4->>Step5: Route to Handoff

    Step5->>Step5: Verify completeness gates
    Step5->>Step5: Compile standardized Discovery Context
    Step5->>User: Present findings/recommend downstream
    Step5->>StateLedger: Record final state + Skill
    Step5->>User: Complete & Handoff
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related issues

Possibly related PRs

Suggested reviewers

  • bmadcode
  • pbean
🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title directly and concisely describes the main change: adding discovery-rigor and workflow-contract skills.
Description check ✅ Passed The description is clearly related to the changeset, explaining what was added, why, and how.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

- rename the discovery-rigor agent entrypoint from thinking-protocol

- remove the obsolete distillate artifact and reset the installation test file
@edamlmmv
Copy link
Copy Markdown
Author

Reopening to include the second commit from the fork branch.

@edamlmmv edamlmmv reopened this Apr 10, 2026
@edamlmmv edamlmmv closed this Apr 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant