home / skills / bacoco / bmad-skills / openspec-change-proposal

openspec-change-proposal skill

safe

/.claude/skills/openspec-change-proposal

This skill creates lightweight change proposals for small bug fixes or simple features, translating requests into structured tasks and acceptance criteria.

npx playbooks add skill bacoco/bmad-skills --skill openspec-change-proposal

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

3.4 KB

---
name: openspec-change-proposal
description: Creates lightweight proposals for L0-1 work.
allowed-tools: ["Read", "Write", "Grep", "Bash"]
metadata:
  auto-invoke: true
  triggers:
    patterns:
      - "fix bug"
      - "small change"
      - "quick feature"
      - "simple fix"
      - "minor update"
    keywords:
      - bug
      - fix
      - small
      - quick
      - simple
      - minor
      - lightweight
  capabilities:
    - proposal-creation
    - change-scoping
    - task-definition
    - lightweight-planning
  prerequisites: []
  outputs:
    - proposal
    - tasks
    - spec-delta
---

# OpenSpec Propose Skill

## When to Invoke

**Automatically activate when user:**
- Says "Fix this bug", "Small change", "Quick feature"
- Asks "Simple fix for [issue]", "Minor update to [component]"
- Mentions "bug fix", "small improvement", "quick change"
- Has a Level 0-1 scoped change (small, low risk, no major unknowns)
- Uses words like: bug, fix, small, quick, simple, minor, lightweight

**Specific trigger phrases:**
- "Fix this bug: [description]"
- "Small change to [component]"
- "Quick feature: [simple feature]"
- "Simple fix for [issue]"
- "Minor update: [description]"
- "Lightweight change proposal"

**Prerequisites:**
- Change is Level 0-1 (small, well-defined)
- No major unknowns or architectural changes
- Existing codebase (not greenfield project)

**Do NOT invoke when:**
- Complex feature requiring PRD (use BMAD instead)
- Architectural changes needed (use bmad-architecture-design)
- Multiple teams coordination (use BMAD)
- Level 2+ complexity (escalate to BMAD)
- Greenfield project (use BMAD workflow)

**Auto-escalate to BMAD when:**
- Scope grows beyond Level 1
- Major unknowns emerge
- Requires cross-team coordination

## Mission
Capture small change requests or bug fixes and translate them into concise proposals and task outlines without invoking the full BMAD workflow.

## Inputs Required
- change_request: description of the existing behavior and desired adjustment
- impact_surface: files, services, or user flows likely affected
- constraints: timeline, risk, or approvals that bound the solution

## Outputs
- `proposal.md` summarizing problem, desired behavior, and acceptance signals (template: `assets/proposal-template.md.template`)
- `tasks.md` listing actionable steps sized for rapid implementation (template: `assets/tasks-template.md.template`)
- `specs/spec-delta.md` capturing ADDED/MODIFIED/REMOVED requirements (template: `assets/spec-delta-template.md.template`)
- Optional `design.md` scaffolded when deeper technical notes are required

`scripts/scaffold_change.py` creates this structure in `openspec/changes/<change-id>/` using the templates above.

## Process
1. Validate Level 0-1 scope using `CHECKLIST.md`.
2. Run `scripts/scaffold_change.py <change-id>` to create the workspace under `openspec/changes/`.
3. Clarify current vs. target behavior and record feasibility notes in `proposal.md`.
4. Draft `tasks.md` and populate `specs/spec-delta.md` using the templates in `assets/`.
5. Highlight dependencies, approvals, and risks, then hand off for review or implementation scheduling.

## Quality Gates
Ensure checklist items pass before finalizing. Escalate to BMAD if scope exceeds Level 1 or introduces major unknowns.

## Error Handling
- If information is insufficient, ask for missing context (screenshots, logs, reproduction steps).
- When risks are high or ambiguity remains, recommend migrating to BMAD discovery-analysis.

Overview

This skill creates concise, lightweight proposals and task outlines for Level 0-1 changes like small bug fixes or minor improvements. It captures the problem, desired behavior, acceptance signals, and a short, executable task list so teams can implement low-risk changes quickly. It auto-validates scope and escalates when the change exceeds Level 1.

How this skill works

The skill validates that the request is small, well-defined, and low risk. It scaffolds a change workspace with a proposal summary, a task breakdown sized for rapid implementation, and a spec-delta documenting requirements added, modified, or removed. If deeper technical notes are needed, it optionally generates a simple design scaffold and flags requirements or missing information.

When to use it

You need a clear, short proposal for a bug fix or minor feature.
Change is Level 0-1: small scope, low risk, no major unknowns.
You want a ready-to-implement task list for rapid delivery.
You must document the exact acceptance criteria and impacted surfaces.
You want automatic escalation when scope or risk increases.

Best practices

Confirm the change meets the Level 0-1 checklist before starting.
Provide reproduction steps, logs, or screenshots when reporting bugs.
List impacted files, services, and user flows as the impact surface.
Keep tasks small and time-boxed for rapid implementation.
Escalate to a broader discovery workflow when unknowns or cross-team work appear.

Example use cases

Fix a user-facing bug that breaks a single API endpoint and needs a small code change.
Apply a minor UI tweak that adjusts copy or layout without architectural work.
Add a simple validation rule to input processing with clear acceptance tests.
Remove a deprecated flag or small config option with limited downstream effects.
Patch a failing unit test by adjusting test data and documenting the rationale.

FAQ

What qualifies as Level 0-1 scope?

Level 0-1 changes are small, well-scoped, low-risk edits with no architectural impact and no major unknowns. If multiple teams or major dependencies are involved, escalate.

What happens if the scope grows?

The skill flags the scope growth and recommends escalation to a broader discovery and design workflow. It can attach the current scaffolding to the escalated process to preserve work.