Sdd Propose

<!-- MEMORY-CONTRACT v1 -->

Memory contract. This command persists across sessions through engram

(registered as an MCP server in this tool). Use this tool's own engram memory

tools to honor the rules below — do not assume any other persistence layer.

>

- Recall before acting: on a continuation keyword ("listo", "dale",

"ready", "where did we leave off"), first search engram for prior work on

this change before starting fresh; summarize what you found, then continue.

- Validate after saving: after any save, search engram back for the key or

a unique phrase — a "saved" tool response is NOT proof. Retry once; if it

still fails, tell the user the save failed. Never report "saved" on the tool

response alone.

- Summarize at close: before ending, write a session summary (goal, work

done, decisions, next steps, files). Recovery is never automatic.

- If engram is unreachable (not installed / not on PATH): emit a visible

warning that engram was not found and that this work will NOT persist. DO NOT

report memory as saved; DO NOT proceed silently as if it had persisted.

Purpose

The proposal defines the WHAT and WHY before entering into technical details. It is the scope contract of the change. Without an approved proposal, there are no specs or design.

For substantial proposals (cross-team scope, multiple stakeholders, or user-facing product changes), optionally pair the proposal with a PRD using `docs/templates/prd-template.md`. The PRD captures problem statement, target users, user stories, NFRs, and acceptance criteria — feeding directly into the sdd-spec phase. Skip the PRD for internal refactors or single-stakeholder changes.

Process

Step 0a — Load project context

Load the project's context and conventions if present. Non-blocking.

Step 0b — Domain context preload

This step is non-blocking: any failure (missing directory, unreadable file, no match) MUST produce at most an INFO-level note in the output. This step MUST NOT produce status: blocked or status: failed on its own.

1. List candidate files: list all .md files in ai-context/features/. Exclude _template.md and any file whose name begins with an underscore (_). If the directory does not exist or is empty after exclusions, skip this step silently and proceed to Step 1.

2. Apply the filename-stem matching heuristic:

• Split the <change-name> on hyphens (-) to obtain stems.
• Discard any single-character stems.
• For each candidate file, compute its domain slug (filename without .md).
• A match occurs when: the domain slug appears anywhere in <change-name> OR any change-name stem appears anywhere in the domain slug (case-insensitive comparison).

3. Load matching files: for each file that matches, read its full contents and treat them as enrichment context for proposal authoring. If multiple files match, load all of them. If a file cannot be read (e.g. permissions issue), log an INFO note and continue — do not block.

4. If no file matches: skip silently. Proceed to Step 1 without error or warning.

5. When files are loaded: note the loaded paths in the Step 6 output summary and include them in the artifacts list (marked as read, not written).

Algorithm reference:

stems = change_name.split("-").filter(s => s.length > 1)
for each feature_file in ai-context/features/ (excluding _ prefix files):
  domain = feature_file.stem  (filename without .md)
  if domain in change_name OR any stem in domain -> match

Examples:

• change add-payments-gateway -> stems [add, payments, gateway] -> matches features/payments.md
• change auth-token-refresh -> stems [auth, token, refresh] -> matches features/auth.md
• change improve-project-audit -> stems [improve, project, audit] -> no match -> skip silently

Step 0c — Spec context preload

Load the change's spec scenarios if present. Non-blocking.

Step 1 — Read prior context

Load the exploration artifact (disk-primary):

• Read docs/sdd/{change-name}/explore.md for full content.
• If the disk file is absent: search prior work for sdd/{change-name}/explore and retrieve it.
• If neither exists: skip — no prior exploration available.

If ai-context/architecture.md exists, consult it for coherence.

Step 2 — Understand the request in depth

If the request is ambiguous, ask:

• What is the problem or need that motivates this change?
• Are there known constraints (performance, compatibility, etc.)?
• Are there parts that are explicitly OUT of scope?

Step 3 — Write proposal

Step 3a — Generate Supersedes section

Before writing the proposal, scan for replacement/removal intent:

1. Read the exploration artifact (if available) and check ## Branch Diff, ## Prior Attempts, and ## Contradiction Analysis sections:

• Read docs/sdd/{change-name}/explore.md; if absent, fall back to searching prior work for sdd/{change-name}/explore and retrieving it.
• If not found: skip exploration input.

2. Scan the user's description and any pre-seeded ## Context Notes in the proposal for patterns: "remove X", "no longer X", "delete X", "replace X with Y". 3. From the above, build the ## Supersedes section:

• If nothing is being removed or replaced: state "None — this is a purely additive change."
• If removals or replacements are found: list each item under ### REMOVED, ### REPLACED, or ### CONTRADICTED subsections as appropriate.

4. Validation: if a Supersedes entry claims to "remove" something but describes adding, emit a MUST_RESOLVE warning and pause for user confirmation.

Step 3a-bis — Requirement Completeness gate

Before persisting, evaluate the assembled draft proposal in memory. This gate is blocking: if any check fails, Step 3b MUST NOT execute. The failure report MUST be presented to the user for correction.

Run BOTH checks in full before emitting any failure report (do not stop at the first finding).

Check 1 — Measurability: For each item under ## Success Criteria:

• FAIL if the item matches any vague predicate: works well, is improved, better, good, robust, clean, nice, properly, as expected.
• FAIL if the item does NOT contain a verifiable verb bound to a concrete artifact, path, command, or numeric value (e.g. "grep returns zero", "file X contains string Y", "step N exists in the heading list").
• Collect each failing item with reason "unmeasurable — predicate not bound to a concrete artifact or value".

Check 2 — Anti-speculation: Scan ONLY ## Scope > Included and ## Success Criteria for speculative marker tokens: might need, nice to have, future, maybe, eventually, someday, if we ever, down the road.

• FAIL if any marker appears in any item in those two sections.
• Collect each failing item with the exact offending marker quoted.

Gate result:

• All checks pass (zero failures): proceed to Step 3b.
• Any check has failures: emit a failure report listing EVERY failing item (not just the count), with its reason and the offending predicate or marker. DO NOT write the artifact or persist a pointer (Step 3b). Present the report to the user and wait for correction before re-evaluating.

Step 3b — Persist proposal

Persist the proposal artifact (disk-primary):

First write docs/sdd/{change-name}/proposal.md with the full proposal markdown, then persist a pointer + summary keyed sdd/{change-name}/proposal, type architecture, scoped to the project.

If the persistence backend is not reachable: still write the disk artifact; skip the pointer only.

Content format:

# Proposal: [change-name]

Date: [YYYY-MM-DD]
Status: Draft

## Intent

[One clear sentence: what problem it solves or what need it covers]

## Motivation

[Why this is necessary now. Business or technical context.]

## Supersedes

[ALWAYS present — even if nothing is superseded. If purely additive: "None — this is a purely additive change."]

### REMOVED (if applicable)

- **[Feature or component name]** (`path/to/file`)
  Reason: [why it is being removed]

### REPLACED (if applicable)

| Old | New | Reason |
|-----|-----|--------|
| [old feature] | [new feature] | [why] |

### CONTRADICTED (if applicable)

- **[Feature or behavior]**: prior context says "[X]", this proposal says "[NOT X]"
  Resolution: [contract superseded / breaking change / deprecation period / stakeholder coordination required]

## Scope

### Included

- [deliverable 1]
- [deliverable 2]
- [deliverable 3]

### Excluded (explicitly out of scope)

- [what will NOT be done and why]

## Proposed Approach

[High-level description of the technical solution.
Does not go into implementation detail — that is the design's job.
Explains the "how" at a conceptual level.]

## Affected Areas

| Area/Module | Type of Change       | Impact          |
| ----------- | -------------------- | --------------- |
| [area]      | New/Modified/Removed | Low/Medium/High |

## Risks

| Risk   | Probability     | Impact          | Mitigation        |
| ------ | --------------- | --------------- | ----------------- |
| [risk] | Low/Medium/High | Low/Medium/High | [how to mitigate] |

## Rollback Plan

[How to revert if something goes wrong.
Must be concrete: which files, which commands, which steps.]

## Dependencies

- [What must exist/be completed before starting]
- [Changes in other parts of the system that this requires]

## Success Criteria

- [ ] [measurable and verifiable criterion 1]
- [ ] [measurable and verifiable criterion 2]
- [ ] [measurable and verifiable criterion 3]

## Effort Estimate

[Low (hours) / Medium (1-2 days) / High (several days)]

Step 4 — Preserve conversation context

This step is non-blocking: if no conversation context is available, skip silently.

1. Scan the user's original request and any pre-seeded ## Context Notes in proposal for:

• Explicit removal/replacement intents ("remove X", "no longer needed", "delete Y")
• Platform or environment constraints ("mobile must not", "not on web", "desktop only")
• Cautions or provisional notes ("careful with Z", "provisional, pending W")

2. If any of the above are found, append a ## Context section to proposal:

## Context

Recorded from conversation at [YYYY-MM-DDTHH:MMZ]:

### Explicit Intents

- **[intent]**: [exact wording or paraphrase from user]

### Platform Constraints

- **[constraint]**: [description]

### Provisional Notes

- **[note]**: [description and condition]

3. If nothing notable is found: skip this section — do NOT add an empty ## Context section.

Step 5 — Contradiction Resolution documentation

This step is non-blocking: only runs if contradictions were detected in exploration.

1. Read the exploration artifact's ## Contradiction Analysis section:

• Search prior work for sdd/{change-name}/explore, retrieve it, and extract the section.
• If not found: skip — no exploration available.

2. For each CERTAIN contradiction found, add a ## Contradiction Resolution section to proposal documenting each one and its resolution approach:

## Contradiction Resolution

### [Feature or behavior name]

**Prior context**: [what the prior spec or archived change said]
**This proposal**: [what this change intends to do instead]
**Resolution approach**: [one of: contract superseded / breaking change with migration / deprecation period / stakeholder coordination required]

3. For each UNCERTAIN contradiction: do NOT add it here — those may be handled by the orchestrator before propose runs as part of a multi-phase flow. If propose runs via direct invocation, document the UNCERTAIN contradictions in ## Risks instead.

Step 6 — Summary to orchestrator

Return a clear executive summary:

Proposal created: [change-name]

Intent: [one line]
Scope: [N deliverables included, M excluded]
Approach: [one line]
Risk: Low/Medium/High
Next step: specs + design (can run in parallel)

Output Contract

{
  "status": "ok|warning|blocked",
  "summary": "Proposal [name]: [intent in one line]. Risk [level].",
  "artifacts": ["docs/sdd/{change-name}/proposal.md"],
  "next_recommended": ["sdd-spec", "sdd-design"],
  "risks": ["[main risk if any]"]
}

Rules

• ALWAYS create the proposal — it is the entry point for all subsequent phases
• Every proposal MUST have a rollback plan and success criteria
• Success criteria MUST be MEASURABLE and VERIFIABLE (not vague)
• Excluded scope is as important as included scope — it prevents scope creep
• I do not go into implementation details — that is the job of sdd-design
• If the proposal is trivial (1-2 line change), I indicate it and suggest skipping the full cycle
• ## Scope > Included items and ## Success Criteria items MUST describe committed, definite work only — they MUST NOT contain speculative markers (might need, nice to have, future, maybe, eventually). Items that are genuinely optional or deferred MUST be placed in ## Excluded. The Requirement Completeness gate (Step 3a-bis) enforces this before persist.