Ss Proposal

Write Technical Proposal

Generate a comprehensive technical proposal from a PRD or requirement description, for any repository shape — a backend service, a frontend app (Web, iOS, Android, Flutter), or a full-stack repository.

Scope note: a proposal is a high-level design document. It answers what the change is, why it's the right approach, and what contracts it introduces or touches — architecture, data flow, key interfaces, alternatives and trade-offs, risks and rollback, milestones. It does not contain implementation detail: no file-by-file edit lists, no full method bodies, no step-by-step coding instructions. That level of detail is the ss-plan skill's job, which consumes this proposal as its input.

When not to use:

• Small bug fixes or config-only changes with no architecture decisions.
• One-line code changes, typo fixes, or copy fixes.
• Changes already fully specified in an existing proposal.

Announce at the start: "Using the ss-proposal skill to generate the technical proposal."

Inputs

• A link to a requirement document that your document-reading tool can fetch, or a plain-text requirement description. If neither is available, ask the user for one.

If the input is a document link, read its content with whatever document-reading tool is available in your environment. Otherwise treat the input as a plain-text requirement description directly.

Hard Gates

Before writing, verify each item. If any fails, stop and explain to the user:

• The PRD/requirement input is readable (the link is accessible, or the text description is substantive).
• The input contains concrete functional or page/feature requirements, not just a concept or goal statement.
• The current repository's code can be inspected to understand its existing architecture (it's compilable/runnable, or otherwise navigable).

If requirements are vague or ambiguous, ask the user for clarification — never assume silently.

Anti-Patterns

The following are proposal failures — never allowed:

Process

Step 1: Scope Check & Repository Boundary

After reading the PRD, identify what's relevant to this repository:

1. Identify this repository's role. Read the project's own docs (README, architecture notes) or analyze the codebase to understand what this repository is responsible for — a backend service, a frontend app, or both.
2. Extract the relevant scope from the PRD. A PRD typically spans multiple services and frontends. Filter out only the parts that belong to this repository.
3. Define the boundary. Clearly identify:
   • What this repository WILL implement (in-scope functionality, pages, or endpoints)
   • What belongs to other repositories (out-of-scope, marked as an external dependency)
   • Integration points with other repositories (APIs to call/expose, cross-app navigation, shared components)
4. Record the repository list. The proposal MUST carry a structured field, Repositories Involved:, in its summary-design section — every repository whose code must change for this requirement (write the current repo's name if it's single-repo). Do not count a shared API-contract repo or spec submodules. Downstream workflows read this field for multi-repo routing — see ../ss-references/multi-repo-detection.md.

If the in-scope work involves 3+ independent subsystems, 5+ independent pages/screens, or spans 2+ sub-apps/micro-frontend modules:

• Suggest splitting into multiple independent proposals.
• Each proposal should be independently deliverable and verifiable.
• Confirm the split approach with the user before continuing.

If the requirement is focused, proceed.

Step 2: Context Gathering

1. Read the PRD/requirement using the method decided in Inputs above. For UI-facing work, focus on user operation flows.
2. Parse related documents. Read the linked issue/task, PRD, related technical proposals (e.g., a companion backend or frontend proposal), and design links if present; extract scope, terms, dependencies, and interaction constraints.
3. Discover API definitions. Search the repository for OpenAPI YAML files (e.g., under api/, contracts/, docs/api/, or any *.yaml/*.yml with OpenAPI markers). If found, read the relevant definitions.
4. Analyze the existing architecture by inspecting the codebase directly. Whichever of these apply to this repository:
   • Module/package structure, layering, and existing design patterns (backend)
   • Navigation/route structure — pages / views / screens / navigator (frontend)
   • State management approach — e.g., DI and data-access patterns (backend); Vuex/Pinia/Redux/Zustand (Web), MVVM/Combine/TCA (iOS), ViewModel/LiveData/Compose state (Android), Provider/Riverpod/Bloc (Flutter)
   • UI building blocks — component library, design system, native views, widgets (frontend)
   • Existing similar feature implementations to use as reference
5. Discover linked designs. If the PRD references a Figma (or similar design-tool) URL and you have a way to read it, fetch the page list and navigation relationships, component hierarchy, and interaction states (hover/active/disabled/error, etc.).

Step 3: Write the Proposal

Generate the proposal following the template in ../ss-references/proposal-template.md. Read that file first, then fill in each section — skipping only the subsections that plainly don't apply to this repository's shape (e.g., a pure backend service skips the UI-contract subsection; a pure frontend app skips the data-model subsection).

The output is a single Markdown document.

Language: write the proposal in the same language as the PRD/requirement input, or the language the repository's other docs already use; default to English if neither gives a clear signal. Code, DDL, and technical identifiers stay in their original form regardless.

Key Principles

• Every design decision states a reason (why this approach?).
• Assumptions are explicit (e.g., "assumes peak QPS < 5000" or "assumes data volume < 10k rows").
• Success criteria are verifiable (e.g., "P99 < 200ms", not "good performance").
• Change points include a "current approach → new approach" comparison, described at the contract level — prose and, where it clarifies an interface, a short pseudocode sketch. Full implementations and file-by-file edit lists don't belong here.
• All schema changes are complete (e.g., full CREATE TABLE with columns, indexes, comments — or the equivalent for this stack).
• All new or changed APIs have full request/response definitions.
• Every UI unit specifies its inputs (props/parameters) and outbound events/callbacks; every page/screen covers Normal/Loading/Empty/Error/Edge-case states.
• Data structures align with the API contract on both sides (field names and types match).

Diagrams

• UML and flow diagrams (architecture, sequence, activity, class, navigation, component hierarchy): use PlantUML or Mermaid syntax in fenced plantuml or mermaid code blocks.
• Simple structural diagrams (directory trees, component/data flow, page hierarchy): use ASCII art.
• Prefer diagrams over long text for system interactions, flows, and relationships.

Step 4: Self-Review

After writing, run this checklist:

1. Requirement coverage

• Check each functional point, page, and feature in the PRD (and in the linked design, if one was provided); each must have a corresponding design in the proposal.
• List and fill any gaps.

2. Scope reduction scan

• Search the proposal for phasing/deferral language: MVP, Phase 2, staged rollout, later iteration, simplified version, core-only, P0-only.
• Every hit must trace to an explicit user instruction recorded in the proposal; otherwise design the missing scope now.

3. Placeholder scan

• Search for: TBD, TODO, "to be determined", "to be added later", "similar to", "refer to".
• Replace all with concrete content.

4. Implementation-depth check

• Scan for full method bodies, complete file listings, or step-by-step coding instructions that have crept past the contract level — trim them back to interface/contract descriptions and defer the rest to ss-plan.

5. Template completeness

• Every applicable section has substantive content.
• The data model (if present) has a complete schema; APIs (if present) have complete request/response definitions; UI contracts (if present) specify props/state/events and cover all page states.
• The risk table has at least 2 risk items.
• The Repositories Involved: field is present (repo list from Step 1; multi-repo routing depends on it).

6. Consistency check

• Class/method/table/component/endpoint names are consistent throughout.
• Modules in architecture diagrams match those in the detailed design.
• Store/state field names match their usage in the detailed design.

7. PlantUML/Mermaid validation

• For each PlantUML diagram, render it via a PlantUML server — the public instance at https://www.plantuml.com/plantuml, or a local/self-hosted renderer if the project configures one — by encoding the source and requesting /png/{encoded} or /svg/{encoded}.
• Verify the rendered image has no syntax-error text.
• If your environment doesn't support image inspection, skip this step.

Fix any issues found immediately, then continue.

Step 5: Independent Review (if subagents are available)

If your tool supports spawning a subagent with fresh context:

• Spawn an independent review agent with:
  • Input: the generated proposal Markdown file.
  • Reference: ../ss-references/proposal-writing.md (quality-standards checklist).
  • Task: review the proposal against every checklist item and report issues.
• The review agent must not have seen the generation process — fresh context is what makes the review independent.
• Fix any issues the reviewer finds before proceeding to output.

If subagents aren't available, skip this step — the Step 4 self-review is sufficient.

Step 6: Output

Write the proposal as a Markdown file to the docs/proposals/ directory in the repository:

• File name format: YYYY-MM-DD-<feature-name>.md
• Example: docs/proposals/2026-05-09-order-refund-flow.md
• Create the docs/proposals/ directory if it doesn't exist.

Step 7: Execution Handoff

After output, present next-step options to the user:

Proposal generated and saved to docs/proposals/. Suggested next steps:

1. ss-plan on docs/proposals/<file>.md — break the proposal into an executable task plan; Phase 0 automatically generates OpenSpec delta specs
2. ss-coding — start multi-agent parallel coding (for smaller requirements)
3. Manual review — have the team review the proposal first

Which do you prefer?