To Prd

To PRD

No interview, just synthesis. The upstream superharness:batch-grill-me, superharness:grill-me, or another requirement discussion has already resolved the open questions. This skill turns that shared understanding into task artifacts. Preserve settled decisions and keep new questioning limited to genuine blocking gaps.

If you find a genuine gap that blocks writing the spec (a decision the conversation never touched), surface it to the user as one focused question. A gap at this stage is an upstream miss, not an invitation to grill again.

The caller must provide an explicit profile: full or profile: lite. Never infer or default the profile. If the caller omitted it, return one focused profile question before creating any artifact.

File Structure

Everything lands in one task directory under the project root:

{project-root}/
├── .superharness/
│   └── tasks/
│       └── {MM}-{DD}-{name}/      ← one directory per task, e.g. 07-08-auth-system
│           ├── prd.md             ← the requirement: 背景/目标/需求描述/风险分析/影响范围
│           ├── task.json          ← task metadata: status/phase/sprint, read by go and parent-thread hooks
│           ├── contract.md        ← Done Definition: verifiable acceptance checklist
│           └── trace.jsonl        ← lifecycle telemetry: seeded by task CLI, transition and prompt events append later
└── src/

Full planning may later add plan.md; delivery may add verification and QA evidence. New workflows do not create implementation protocol files. to-prd owns these four initial artifacts and nothing else.

Write the Artifacts

Create the task directory, write three semantic files, then use the task CLI to generate the trace artifact:

1. Spec (prd.md): Write the validated design to .superharness/tasks/{MM}-{DD}-{name}/prd.md

   • {MM}-{DD} is the current date (zero-padded month and day)

   • {name} is a short kebab-case identifier for the topic (e.g., 04-03-auth-system)

   • Record decisions, not code: capture what was decided and why. Wiki-sourced facts keep their document title/ID attribution.

   • A prd records the requirement, not the technical solution — how to build it belongs to writing-plans. Use this exact structure:

     # {标题}
     
     ## 背景
     
     ## 目标
     ### 业务目标
     ### 技术目标
     
     ## 需求描述
     
     ## 风险分析
     
     ## 影响范围
     

2. Contract (contract.md): Create .superharness/tasks/{MM}-{DD}-{name}/contract.md from the confirmed spec before constructing task metadata. Persist both the confirmed public seams and objectively checkable acceptance slices:

   # Done Definition — {name}
   
   ## Test Seams
   - <confirmed public callable boundary>
   
   ## Acceptance Checklist
   - [ ] <verifiable acceptance slice derived from the spec>
   - [ ] ...
   - [ ] focused tests / typecheck / lint / test 全过
   - [ ] 两轴审查（Spec + Standards）单轮 PASS
   

   Every item must be objectively checkable and name how it is checked: a focused test, an integration/E2E gate, or a reviewer/manual check. Objectively checkable does not mean unit-tested — items may be covered by QA, E2E, or reviewer verification, and manual procedures for verified behavior land here so finishing actually checks them. Do not use vague statements such as "works correctly".

3. Task metadata (task.json): Create .superharness/tasks/{MM}-{DD}-{name}/task.json. Task creation is the only place that writes initial phase/status directly.

   Full initial state:

   {
     "name": "{name}",
     "title": "Human-readable title from the spec",
     "profile": "full",
     "status": "planning",
     "phase": "plan",
     "worktree_path": null,
     "implementation": {
       "base_sha": "<full HEAD SHA>"
     },
     "sprint": {
       "current": 0,
       "total": 0
     },
     "tasks": [],
     "created_at": "ISO date",
     "updated_at": "ISO date"
   }
   

   Lite initial state:

   {
     "name": "{name}",
     "title": "Human-readable title from the spec",
     "profile": "lite",
     "status": "in_progress",
     "phase": "implement",
     "worktree_path": null,
     "implementation": {
       "base_sha": "<full HEAD SHA>"
     },
     "sprint": {
       "current": 1,
       "total": 1
     },
     "tasks": [
       {
         "id": 1,
         "name": "observable acceptance outcome",
         "status": "pending",
         "seams": ["confirmed public seam"],
         "behavior_slices": ["confirmed acceptance slice with verification mode"]
       }
     ],
     "created_at": "ISO date",
     "updated_at": "ISO date"
   }
   

   Resolve <full HEAD SHA> with git rev-parse HEAD before writing any task artifact. The explicit caller-provided profile selects the matching initial state. After creation, every lifecycle phase/status change uses superharness task transition {task-id} {phase}.

   Full writing-plans populates task items later during plan. For Lite, atomically derive 1–3 task items from the confirmed prd.md and contract.md acceptance slices while creating task.json. Construct the complete Lite task object in memory and write task.json once; never create an empty tasks array and mutate it after the task has entered implement. Each item must keep one coherent observable outcome, include at least one confirmed seam and behavior slice, use consecutive ids starting at 1, and set sprint.current to 1 plus sprint.total to the item count. Each slice states its verification mode: tested only for risk-bearing behavior (branching, boundaries, transformation, state transitions, protocol compatibility); everything else is verified with the gate that covers it. If the confirmed scope cannot fit 1–3 coherent items, stop and ask the user to select Full.

   Every generated item uses this shape:

   {
     "id": 1,
     "name": "observable task outcome",
     "status": "pending",
     "seams": ["public callable boundary"],
     "behavior_slices": ["input, observable result, expectation source, tested risk:<error space> | verified gate:<bound check>"]
   }
   

4. Trace seed: after prd.md, contract.md, and task.json are complete, generate .superharness/tasks/{MM}-{DD}-{name}/trace.jsonl through the controlled CLI:

   superharness task start {MM}-{DD}-{name} --requirement "{one-line requirement summary}"
   

   Pass only the task id and semantic summary. The CLI derives the timestamp, phase, profile, event, and detail schema from task metadata. superharness task transition appends state changes and the user-prompt hook appends user interventions. Without the seed, tasks created outside the go workflow have no trace starting point.

5. Commit all files to git — prd.md, task.json, contract.md, and trace.jsonl.

Spec Self-Review

After writing the spec document, look at it with fresh eyes:

1. Placeholder scan: Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
2. Internal consistency: Do any sections contradict each other? Does the architecture match the feature descriptions?
3. Scope check: Is this focused enough for a single implementation plan, or does it need decomposition?
4. Ambiguity check: Could any requirement be interpreted two different ways? If so, pick one and make it explicit.

Fix any issues inline. No need to re-review — just fix and move on.

User Review Gate

This gate remains after step 5 has created and committed prd.md, contract.md, task.json, and trace.jsonl. Read .superharness/config.yaml and ask the user to choose:

1. Continue without adversarial review — preserve the existing user review behavior.
2. Run PRD adversarial review — invoke superharness:adversarial-review with the task-id and target prd when review.mode is on-demand.

When review.mode is off, omit the adversarial option and use the existing prompt:

"Spec written and committed to .superharness/tasks/{MM}-{DD}-{name}/prd.md. Task artifacts (task.json, contract.md) created. Please review the spec and let me know if you want to make any changes."

After adversarial review finishes, return to this same user review gate. Adversarial review does not count as the user's approval.

Wait for the user's response. If they request changes, make them and re-run the self-review. Only finish once the user approves.

After Approval

This skill ends here; the caller owns the next step. The go full flow continues with superharness:writing-plans. The go Lite flow continues implementation from the 1–3 task items already persisted here. When invoked standalone, report the created task directory name and the profile-independent continuation command /superharness:go --task {task-id}. Go reads the stored profile from task.json.

Red Flags

• Re-asking questions the conversation already answered
• Writing file paths or code snippets into prd.md as requirements — they go stale; record decisions instead
• Skipping the self-review or the user review gate
• Inventing requirements that were never discussed to make the spec look complete
• Inferring a missing profile or writing artifacts before the caller provides one