Creates a change proposal with clear intent, defined scope, and technical approach.

/sdd-propose <change-name>

status: blocked

status: failed

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).

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

• 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

• mem_search(query: "sdd/{change-name}/explore")

  →

  mem_get_observation(id)

  for full content.
• If not found: skip — no prior exploration available.

ai-context/architecture.md

• 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?

1. Read the exploration artifact (if available) and check

   ## Branch Diff

   ,

   ## Prior Attempts

   , and

   ## Contradiction Analysis

   sections:

   • mem_search(query: "sdd/{change-name}/explore")

     →

     mem_get_observation(id)

     .
   • 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.

• [Feature or component name] (

  path/to/file

  ) Reason: [why it is being removed]

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

• [deliverable 1]
• [deliverable 2]
• [deliverable 3]

• [what will NOT be done and why]

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

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

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:

undefined

• [intent]: [exact wording or paraphrase from user]

• [constraint]: [description]

• [note]: [description and condition]

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

1. Read the exploration artifact's

   ## Contradiction Analysis

   section:

   • mem_search(query: "sdd/{change-name}/explore")

     →

     mem_get_observation(id)

     → extract 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:

undefined

• 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