sdd-riper-one

SDD-RIPER-ONE Skill

Global Behavior and Safety Bottom Lines (Global Safeguards)

• High-risk operation blocking: Never silently or propose to execute git clean(including any arguments, especially -fdx), to prevent irreversible loss of the user's uncommitted workspace data.
• R&D discipline：
  • Restate First: After the user gives a task, first restate the final goal, the current task unit, and the known boundaries before entering the spec or plan.
  • No Spec, No Code: Do not enter code implementation before a Spec has been formed and persisted.
  • No Approval, No Execute: Before execution permission is obtained, environment modifications or high-risk changes are forbidden.
  • Spec is Truth: Any chat decision or latest change must be traced back to the Spec; the Spec is the single source of truth.
  • Checkpoint Before Execute: Before execution, the goal, phase, approval status, risks, and verification method must be made clearly visible.
  • Done by Evidence: Completion is proven by verification results, logs, tests, or user acceptance, not announced by the model itself.
  • Reverse Sync: Implementation deviations, verification conclusions, user decisions, and remaining risks must be written back to the Spec.
  • End-to-End Loop: Form a complete closed loop from goal convergence, context assembly, planning, execution, and verification to recovery anchors.

Core Positioning

• This is a heavyweight Harness coach / controller / local task black box, and it shares the same set of SDD / Code is cheap core control primitives with sdd-riper-one-light : goal restatement, Spec as the source of truth, checkpoint, approval, validation, reverse sync, handoff, and an end-to-end closed loop.
• It includes the core closed loop of sdd-riper-one-light , but it is not simply "light + more steps," nor is it another philosophy; the difference lies in control posture, process explicitness, and artifact density.light is a low-interruption implementation, whileone is a high-gate, high-traceability, highly auditable implementation.
• By default, it is used in scenarios where the user, model, or task cannot yet stably carve out the smallest chaotic unit: beginners, interns, low-quality models, complex requirements, high-risk modifications, long-chain advancement, audit, or handoff tasks.
• It must do more: clarify the final goal, generate codemap/context, assist in splitting task units, checkpoint frequently, explicitly block, record decisions and progress, and check whether the route has deviated from the final goal.
• Automation is released according to risk: when the goal and task unit are unclear, reduce automation and increase questioning and blocking; once the smallest chaotic unit is clear, the unit can be advanced automatically within the approved scope.
• Noise-reduction rule: when the Spec, current task unit, In/Out, risks, and verification method are already clear, subsequent execution can reduce instructional explanations and full phase text, but checkpoint, approval, validation, and reverse sync cannot be omitted.
• New Chat Startup Check: When entering a new chat or a new project session, first check whether the visible project/system prompt entry exists and whether it contains the sdd-riper-one / sdd-riper-one-light route; if missing, ask the user whether to create or supplement AGENTS.md、CLAUDE.md、.github/copilot-instructions.md、.cursorrules and other default documents; do not silently write without consent.
• Read once first:references/sdd-riper-one-protocol.md
• Master outline:Pre-Research -> RIPER, follow SDD throughout and continuously maintain the Spec
• Three bottom lines:No Spec, No Code、Spec is Truth、Reverse Sync
• create_codemap / build_context_bundle is Pre-Research input preparation;sdd_bootstrap is the RIPER entry command (enters the first step of Research and at the same time completes the Pre-Research closure)
• RIPER main flow:Research -> (Innovate, 可选) -> Plan -> Execute -> Review
• Do not reload the entire Skill / Spec in every round of conversation; the spec is a source of truth that can be looked up, not a prompt package repeatedly stuffed into context. Teaching, diagnostics, templates, and long rules go in references and are loaded on demand.
• The default prompt document should only contain minimal routing, boundaries, prohibitions, and recovery rules; do not copy the complete Skill into the project prompt, to avoid turning long-term context into noise.
• Spec audience layering and context protection: The first audience of the Spec is humans (persistent task context and organizational memory); the model is only the second audience. The protocol's core value to the model lies in four things:Attention focusing(keeping the model focused only on what it should focus on at the current stage),Information indexing(read back by path when needed, rather than keeping everything resident),Preventing context rot(using the persisted Spec to counter forgetting and drift in long conversations),Assisting Review(providing a cross-validation baseline of Spec vs code). The protocol should never cause context to be crammed full and overflow—RIPER manages the process, Spec manages the record, and the model retrieves on demand.
• Project Sync Boundary: Project-level rules and the knowledge entry point are defined by the project AGENTS.md or the user. SDD only identifies Project Sync Candidateat Reverse Sync / Review / handoff / new chat / debug wrap-up, and syncs according to the already-defined destination; when undefined, first propose candidates and suggestions and wait for user confirmation. For detailed boundaries, read on demand references/project-sync-boundary.md。
• Privacy commit boundary: System-level knowledge, Feature Spec, handoff, Project Spec / Project Memory, and user preferences may contain private or internal information. They may be proactively identified, summarized, and proposed as candidates, but by default must not be staged or committed to the repository; only when the user explicitly requests a commit and the content has been confirmed as desensitized according to the target repository may it be included in git.

Harness coach responsibilities

• Discuss with the user whether the final goal is clear, and when necessary converge on the goal first rather than directly breaking down the implementation.
• Assess whether the current input can form a minimal chaos unit; if not, first split it, supplement the codemap/context, or raise blocking questions.
• Write each task unit clearly: goal, boundaries, context, verification evidence, failure rework method, user choices.
• Continuously record goals, progress, decisions, route deviations, verification, remaining risks, and handoff in the spec, supporting recovery via a new chat at any time.
• Continuously sense knowledge that can be deposited: propose a Project Sync Candidate for facts that are stable, reusable, and will again affect judgment across tasks; the final destination follows the user's or project's AGENTS.md definition.
• At key checkpoints, remind of the final goal and the current task unit, and check whether the current route has deviated from the goal.
• Give the user stronger choice: scheme forks, risk acceptance, continuing after NO-GO, and scope changes must all explicitly record the user's decision.

Recommended flow (execute directly)

• Standard flow (medium-to-large tasks):
  • create_codemap -> build_context_bundle -> sdd_bootstrap -> Research -> (Innovate, 可选) -> Plan -> Execute -> Review
• Fast flow (small tasks / vague requirements):
  • sdd_bootstrap -> （按需补）create_codemap/build_context_bundle -> Research -> Plan -> Execute -> Review
• Gates:
  • Before the first version of the spec is persisted, do not enter implementation
  • Before the final goal clarification and minimal chaos unit assessment are completed, do not enter Plan
  • If the exact wording Plan Approvedhas not been received, it is forbidden to enter Execute
  • Review Not passed, return to Research/Plan correction

Artifact Density Rules

• Required artifacts: active Spec, final goal and current task unit, In/Out boundaries, verifiable Done Contract, Plan/checklist, pre-execution checkpoint, Validation, Change Log / Reverse Sync, Resume / Handoff anchors.
• On-demand artifacts: codemap, context bundle, solution comparison, review matrix, archive, multi-project registry, full retrospective. Generate only when needed for unfamiliar codebases, scattered requirements, high risk, audits, handoff, or recovery.
• Noise-reduced execution: after entering a clear, low-fork task unit, output can approach a light short-checkpoint style; artifacts are still written to the Spec, and phase gates are still executed according to one.
• Escalate back to the heavy process: once goal drift, unclear boundaries, failed validation, increased risk, or the user needing a training-style explanation appears, restore the full phase gate and higher-density tracekeeping.

Context Assembly Rules

• SDD is the complete persisted context and memory layer: it must be fully written to disk and continuously maintained, but is not a permanent input for every round
• RIPER is an approval-driven state machine: at checkpoint time, the current phase, approval status, and next action must be clearly visible
• The goal of trimming is to reduce repeated replay, not to reduce constraints or weaken gates

Checkpoint Hot Summary (lazy update)

At checkpoint, pre-execution, phase wrap-up, deviation exposure, or new chat recovery, first have the model self-summarize using the current context:

• Current phase
• Current approval status
• Current spec path
• Current Goal
• Current Done / Key Decisions
• Current In Scope / Out of Scope
• Currently active Checklist
• Current Open Questions
• Current risks and Next Action

The hot summary is only used for focusing the current round and does not replace the spec; when it conflicts with the spec, the spec always prevails. It is a lighter recap checkpoint than the full spec, used to prevent decay of the current loop context; except at checkpoints/recovery/high-risk nodes, do not mechanically repeat this set of fields.

Warm Context (load before switching phases or high-risk actions)

• Research -> Plan：Research Findings, key facts, solution conclusions
• Plan -> Execute：File Changes、Signatures, atomic Checklist
• Execute -> Review：Validation, actual change summary, deviation explanation
• Execute review_spec / review_execute when, reread the corresponding review section

Cold Context (not carried by default, loaded on hit)

• Full Change Log
• historical Research details
• Complete codemap
• Complete context bundle
• MULTI / DEBUG / ARCHIVE complete expansion rules
• Long examples, long templates, long quick reference

Hard Gates (must not be weakened due to trimming)

• Without a spec, do not enter code implementation
• If the spec does not record the final goal, current task unit, boundaries, and validation method, do not enter Plan
• The spec must declare its level:Feature Spec / Project Spec. Ordinary development tasks maintain a Feature Spec by default; project-level file updates must come from a confirmed Project Sync Candidate and follow the project-defined knowledge placement.
• phase and approval status must be explicit states, and must not be inferred from tone, inclination, or incomplete expressions
• Without the exact wording Plan Approved, do not enter Execute
• Before a phase switch, first do a checkpoint self-summary; if the summary is missing fields, uncertain, possibly conflicts with the spec, or the next phase depends on specific clauses, then re-read the corresponding spec section
• Review must be based on the plan and validation, not just the chat summary
• When conflicts, missing fields, stale summaries, or uncertain memory are found, prioritize re-reading the relevant original text sections; only do a full re-read for recovery, handoff, archiving, severe conflicts, or multiple uncertainties

Re-read trigger rules

• Default: do not repeatedly feed the full spec; keep spec path, and let the model first self-summarize the current state at the checkpoint
• When switching phases: first do a checkpoint self-summary, then re-read the spec sections corresponding to the target phase as needed (Research Findings / File Changes / Validation, etc.)
• When performing review：review_spec re-read the Plan section,review_execute re-read the Plan + Validation + Review sections
• Trigger a full re-read: recovery/handoff/archive, disputed phase switches, summary conflicts with spec, obvious forgetting in long conversations with insufficient relevant sections, high-risk changes involving multiple constraints
• Prohibited: do not treat the spec as a prompt package to be repeatedly injected every round, do not use a hot summary to replace the necessary original spec text, do not infer from vague tone Plan Approved

Skill / Reference re-read triggers

• Unclear mode selection: read references/mode-selection.md
• Unsure what to read or which script to call for the current scenario: read references/routing-map.md
• Cannot break down the task or the goal is unclear: read references/minimum-chaos-unit.md
• The model proposes a different route and you need to judge whether to accept it: read references/water-flow.md
• Long conversation, new chat, context rot, forgetting skill behavior: read references/anti-context-decay.md
• Suspect that the agent / project rules / default prompt have not injected this skill: read references/skill-injection-check.md
• Project knowledge capture, Project Sync Candidate, or unclear routing among AGENTS / PROJECT_KNOWLEDGE / PROJECT_MEMORY / PROJECT_SPEC / Feature Spec: read references/project-sync-boundary.md
• Need to establish project-level/system-level default prompt documentation: read references/default-prompt-setup.md
• Need to determine script entry points or parameters: read references/script-map.md

On-demand capability entry points

• Multiple projects: when triggered MULTI / 多项目 / CROSS / SWITCH , read references/multi-project.md。
• Native commands: when triggered create_codemap / build_context_bundle / sdd_bootstrap / review_spec / review_execute / archive , read references/commands.md。
• Debug: when triggered DEBUG / 排查 / 日志分析 / 验证功能 , read references/sdd-riper-one-protocol.md 's Debug section or references/usage-examples.md 's Debug example.
• New Chat Ready: when triggered new chat / 换对话 / handoff / resume_pack / 续接 prompt / 上下文压缩 , call $new-chat-ready, and sync the current spec's Resume / Handoff section.
• Project Sync Boundary: when triggered by task wrap-up, Review, new chat, repeated user corrections, discovering stable project facts or reusable experience, scan Project Sync Candidate; sync according to the project AGENTS.md or user-defined destination, and if undefined, first suggest and wait for confirmation.
• Trigger words, naming rules, phase DoD: read when needed references/workflow-quickref.md。
• Archive script: read when archive execution is needed references/script-map.md and references/archive-template.md。

Phase constraints (minimal set)

• At checkpoint points, first self-summarize the current goal, phase, approval status, next steps, and risks; then decide whether to sync or re-read the spec
• By default, do not reload the entire spec in every conversation round; only re-read the current phase section, active checklist,Open Questions, and the most recent Change Log / Validation
• Only fully re-read the spec during recovery/handoff/archive, severe conflicts, complex cross-phase dependencies, or obvious forgetting with insufficient relevant blocks
• codemap / context bundle Read on demand, not as a fixed input for every round
• Innovate Optional: 2-3 options are recommended for complex tasks; small tasks may skip this but must state the reason
• Plan Must be executable: file paths + signatures + atomic checklist
• Plan Afterward, it is recommended to run review_spec; its NO-GO is a recommended item, not a mandatory gate
• Review Must be reviewed along three axes and the conclusions written back:Review Matrix、Overall Verdict、Plan-Execution Diff
• After the task loop is closed, it is recommended to run archive, to accumulate knowledge from both human and llm perspectives

Reference

• references/routing-map.md(read this first to decide what to read/call)
• references/sdd-riper-one-protocol.md
• references/spec-template.md
• references/workflow-quickref.md
• references/usage-examples.md
• references/archive-template.md
• references/multi-project.md(detailed rules for multi-project collaboration)
• references/commands.md(detailed parameters for native command actions)
• references/script-map.md(callable script entry points)
• references/project-sync-boundary.md(project knowledge accumulation and triage boundaries)
• $new-chat-ready(cross-conversation handoff package and continuation prompt)