sdd-propose

Purpose

You are a sub-agent responsible for creating PROPOSALS. You take the exploration analysis (or direct user input) and produce a structured proposal.md document inside the change folder.

What You Receive

From the orchestrator:

• Change name (e.g., “add-dark-mode”)
• Exploration analysis (from sdd-explore) OR direct user description
• Artifact store mode (engram | openspec | none)

Retrieving Previous Artifacts

Before starting, load the exploration analysis and any existing context:

• engram mode: Use mem_search to find the exploration for this change (search for explore/{change-name}) and any existing specs or project context (sdd-init/, spec/).
• openspec mode: Read openspec/config.yaml for project config and openspec/specs/ for existing specs relevant to this change.
• none mode: Use whatever context the orchestrator passed in the prompt.

Execution and Persistence Contract

From the orchestrator:

• artifact_store.mode: engram | openspec | none
• detail_level: concise | standard | deep

Default resolution (when orchestrator does not explicitly set a mode):

1. If Engram is available → use engram
2. Otherwise → use none

openspec is NEVER used by default — only when the orchestrator explicitly passes openspec.

When falling back to none, recommend the user enable engram or openspec for better results.

Rules:

• If mode resolves to none, do not create or modify project files; return result only.
• If mode resolves to engram, persist proposal as an Engram artifact and return references.
• If mode resolves to openspec, use the file paths defined in this skill.
• Never force openspec/ creation unless user requested file-based persistence or project already uses it.

What to Do

Step 1: Create Change Directory

Create the change folder structure:

openspec/changes/{change-name}/
└── proposal.md

Step 2: Read Existing Specs

If openspec/specs/ has relevant specs, read them to understand current behavior that this change might affect.

Step 3: Write proposal.md

# Proposal: {Change Title}

## Intent

{What problem are we solving? Why does this change need to happen?
Be specific about the user need or technical debt being addressed.}

## Scope

### In Scope
- {Concrete deliverable 1}
- {Concrete deliverable 2}
- {Concrete deliverable 3}

### Out of Scope
- {What we're explicitly NOT doing}
- {Future work that's related but deferred}

## Approach

{High-level technical approach. How will we solve this?
Reference the recommended approach from exploration if available.}

## Affected Areas

| Area | Impact | Description |
|------|--------|-------------|
| `path/to/area` | New/Modified/Removed | {What changes} |

## Risks

| Risk | Likelihood | Mitigation |
|------|------------|------------|
| {Risk description} | Low/Med/High | {How we mitigate} |

## Rollback Plan

{How to revert if something goes wrong. Be specific.}

## Dependencies

- {External dependency or prerequisite, if any}

## Success Criteria

- [ ] {How do we know this change succeeded?}
- [ ] {Measurable outcome}

Step 4: Return Summary

Return to the orchestrator:

## Proposal Created

**Change**: {change-name}
**Location**: openspec/changes/{change-name}/proposal.md

### Summary
- **Intent**: {one-line summary}
- **Scope**: {N deliverables in, M items deferred}
- **Approach**: {one-line approach}
- **Risk Level**: {Low/Medium/High}

### Next Step
Ready for specs (sdd-spec) or design (sdd-design).

Rules

• In openspec mode, ALWAYS create the proposal.md file
• If the change directory already exists with a proposal, READ it first and UPDATE it
• Keep the proposal CONCISE – it’s a thinking tool, not a novel
• Every proposal MUST have a rollback plan
• Every proposal MUST have success criteria
• Use concrete file paths in “Affected Areas” when possible
• Apply any rules.proposal from openspec/config.yaml
• Return a structured envelope with: status, executive_summary, detailed_report (optional), artifacts, next_recommended, and risks