/synthex:write-implementation-plan/synthex:write-implementation-plan

#What it does, end-to-end

/synthex:write-implementation-plan/synthex:write-implementation-plan is the Plan-phase entry point: the command that takes a PRD and produces a peer-reviewed, milestone-and-task implementation plan you can hand to /synthex:next-priority/synthex:next-priority.

Each invocation:

1. Reads the PRD at docs/reqs/main.md (configurable via documents.requirements). The PRD is the input contract — every plan task points back to a PRD requirement.
2. PM drafts the plan. The Product Manager agent structures the work into phases → milestones → tasks, assigns complexity estimates (S/M/L), surfaces dependencies, and tags acceptance criteria with their type ([T] / [H] / [O]).
3. Parallel reviewer pass. The Architect, Designer, and Tech Lead review the draft in parallel. Each emits structured findings; the Findings Consolidator deduplicates and ranks them by severity.
4. PM iterates. The PM addresses every finding at or above min_severity_to_address (default high). The cycle repeats up to max_cycles times (default 3 for plans — one extra cycle since plan defects ripple downstream).
5. Plan saved. Final output lands at docs/plans/main.md (configurable via documents.implementation_plan). The plan includes phases, milestones, tasks, decisions, open questions, and parallelizable batches per milestone.

#Reviewer roster

Default reviewers (configurable in .synthex/config.yaml):

implementation_plan:
  reviewers:
    - agent: architect
      enabled: true
      focus: "Technical architecture, feasibility, NFR coverage, missing technical tasks"
    - agent: designer
      enabled: true
      focus: "Design tasks, UX impact, visual/interaction design clarity"
    - agent: tech-lead
      enabled: true
      focus: "Task clarity, acceptance criteria, parallelizability, dependency accuracy"

Add specialists for project-specific concerns:

implementation_plan:
  reviewers:
    - agent: compliance-reviewer
      enabled: true
      focus: "Regulatory compliance, audit-trail requirements"

#What makes a good plan

The reviewer prompts are tuned to surface the qualities a plan needs:

• Every task has acceptance criteria. No tag-less tasks. Each criterion is [T], [H], or [O]. Most tasks have at least one [T] because untestable claims tend to indicate unclear scope.
• Parallelizability is explicit. The plan calls out which tasks can run in parallel per milestone, and which sequence dependencies block which.
• Decisions are recorded. Plans include a Decisions table with rationale; the reviewers will flag implicit decisions made during planning that should have been surfaced explicitly.
• Open questions are named. A plan with no open questions is suspicious — most non-trivial work has at least one unresolved item. Calling it out lets future-you see what was unsolved and why a default was chosen.

#Common failure modes

The reviewers are calibrated to catch:

• Vague tasks. "Improve search" is not a task. "Reduce p95 search latency from 800ms to ≤300ms on the documented dataset" is.
• Missing acceptance criteria. Every task gets at least one criterion. The reviewers reject tasks that ship without.
• Untestable [T]s. A [T] tag commits the task to having a passing automated test. When the criterion is structurally untestable, the reviewers either downgrade it to [H] or split it.
• Cross-phase boundary creep. Tasks that span two phases (e.g., "ship to prod and run a retrospective") get split — phase boundaries exist for a reason.

#Parameters

#When to re-run it

Run /synthex:write-implementation-plan/synthex:write-implementation-plan once per PRD, then iterate the PRD and plan together as the project progresses. For mid-project re-planning (new PRD addendum, new constraint), re-running produces a new plan; preserve the old plan as docs/plans/<date>-archived.md if the lineage matters.

You usually do NOT regenerate the plan after a single completed task — that's /synthex:next-priority/synthex:next-priority's job, which appends completion notes to the existing plan.

#Native looping

Pass --loop to iterate plan-writing until the plan stabilizes — useful when the PRD has enough open ends that one invocation isn't enough to converge. Iteration state lives in .synthex/loops/<loop-id>.json so a stalled or crashed session can be resumed cleanly. See Native looping for the full framework contract.

Emission rule. The loop terminates when all of:

• The plan file has been written to disk.
• Every PRD requirement is reflected in at least one task.
• The plan contains no TBD, <placeholder>, ???, or open-question markers in task descriptions or acceptance criteria.
• A follow-up iteration would not add new tasks or refine existing ones — typically when reviewers' suggested edits have been incorporated and no further drafts are pending.

The promise is not emitted while a review cycle is still in flight or unresolved markers remain.

Example. Drive a long PRD to a stable plan over many iterations:

/synthex:write-implementation-plan --loop \
  --completion-promise "PLAN_STABLE" \
  --max-iterations 15 \
  prd_path=docs/reqs/payments-v2.md