Skip to content

SoW Workflow — End-to-End Prompt

Use this prompt to run the full workflow that produces a production-ready Statement of Work. It orchestrates multiple skills in sequence, with mandatory human-in-the-loop (HITL) review gates between every phase.

Why HITL gates matter

Each phase builds on the outputs of the previous phase. Errors, wrong assumptions, or misunderstandings that pass uncorrected through a gate will compound into every downstream document — requiring expensive rework (both in LLM tokens and human time). A 2-minute correction at the gap analysis stage avoids a 30-minute re-run of the plan, SoW, and timeline.

Rule: Never proceed to the next phase until the user has explicitly approved the current phase's output. If the user provides corrections, apply them and re-present the corrected output for approval before moving on.

The workflow produces these output documents:

  1. Gap analysis — [system]-gap-analysis.md
  2. Remediation plan — [system]-remediation-plan.md (includes CARES and external dependencies)
  3. Skills summary — [system]-skills-summary.md
  4. Clarification questions — [system]-clarification-questions.md (if gaps exist)
  5. Technical detail request — [system]-technical-detail-request.md (if codebase data needed)
  6. Statement of Work — [system]-sow.md
  7. Timeline — [system]-timeline.md (with Mermaid Gantt chart)

Phase 1 — Gather inputs

Skill: gather-inputs

Before starting any analysis, collect the following from the user. Ask these as clarifying questions if not already provided.

Do not proceed to Phase 2 until all 6 input areas are addressed. Missing inputs produce assumption-heavy gap analyses that cascade errors into the plan and SoW.

1.1 System under assessment

Ask the user:

What system are we assessing? Please provide:
- System name and one-sentence description
- Current deployment model (local, Docker, cloud, etc.)
- Approximate size (endpoints, pages, database size, user count)
- Primary tech stack (language, framework, database, frontend)

1.2 Current state documentation

Ask the user:

What documentation exists for the current state? Please share or point me to:
- Architecture document or technical design doc
- README or developer setup guide
- Any existing gap analysis, audit, or review findings

If no documentation exists, we can work from the codebase directly — but a
doc-first pass followed by a codebase supplement produces better results.

1.3 Target state / reference patterns

Ask the user:

What should we compare against? Options:
(a) Reference repos in this workspace (e.g. quota-keeper-api, feature-flagger-ui)
(b) A written standard or checklist (share the doc)
(c) Team conventions / engineering library skills
(d) A combination of the above

If using reference repos, which ones? I'll deep-dive into their CI/CD,
testing, auth, observability, docs, and deployment patterns to establish
the target standard.

1.4 Codebase access

Ask the user:

Do we have access to the actual source code?
(a) Yes — it's in this workspace or I can clone it
(b) No — we're working from documentation only
(c) The business user / owner has access and can run commands for us

If (c), I'll generate a structured prompt they can paste into their LLM
to extract technical details from the codebase (dependencies, Dockerfile,
test inventory, logging config, etc.).

1.5 Organisational context

Ask the user:

A few organisational details that shape the SoW:
- Does the company use service tiering for SLA? (e.g. T1/T2/T3)
- What platform hosts CI/CD? (Azure DevOps, GitHub Actions, etc.)
- Is there a Technical Design Authority (TDA) that approves technology decisions?
- Who provisions Azure infrastructure? (self-service, Central IT, platform team)
- Is there a change management process for production deployments? (ServiceNow, etc.)
- Any known constraints? (budget, timeline, team size, compliance requirements)

1.6 Templates and blueprints

Ask the user:

Do you have any of the following to use as templates?
- Existing SoW from a similar engagement (I'll match the format)
- Pipeline YAML from a reference repo (I'll model the pipeline items on it)
- Infrastructure-as-code templates (Bicep/Terraform for Azure resources)
- Engineering library skills (I'll map plan items to available skills)

If skills exist in .github/skills/ or an engineering library repo, point me
to them and I'll produce a skills summary showing coverage and gaps.

1.7 Build input register and cross-reference

Once inputs are collected, follow the gather-inputs skill to:

  1. Document every fact in an input register with source, date, and confidence level (High / Medium / Low / Unknown).
  2. Cross-reference sources — compare facts across all input documents. When two sources disagree, apply the source-of-truth priority:
  3. Live system / running code output (highest)
  4. Code files (pyproject.toml, Dockerfile, package.json)
  5. CI/CD pipeline YAML
  6. Technical supplement (codebase-derived)
  7. Architecture document
  8. README
  9. Verbal/chat statements (lowest)
  10. Detect superseded information — when a newer source updates a fact, mark the older entry as superseded and record the new value.
  11. Flag inconsistencies — produce an inconsistencies table with resolution status (Resolved / Open).
  12. Flag unknowns — for each Low/Unknown confidence fact, recommend: Collect (add to follow-up request), Assume (state assumption with "Impact if Wrong"), or Escalate (present options for HITL decision).

HITL Gate 1 — Input confirmation

Before proceeding, summarise back to the user what you have:

Here's what I'm working with. Please confirm or correct:

**System:** [name] — [description]
**Current state source:** [doc name / codebase access / both]
**Target standard:** [reference repos / checklist / skills]
**Codebase access:** [direct / doc-only / business user proxy]
**Org context:** [CI platform, tiering, TDA, provisioning model]
**Templates:** [what was provided]

**Input register:** [N] facts recorded — [M] high, [P] medium, [Q] low/unknown confidence
**Inconsistencies found:** [count] — [resolved] resolved, [open] open
**Unknowns requiring your decision:** [count]

[List each open inconsistency with sources and recommended resolution]
[List each unknown with recommended action and options if escalating]

I need these resolved before starting the gap analysis — errors here
will compound through every later document.

Wait for explicit approval before proceeding to Phase 2.

Phase 2 — Gap analysis

Skill: gap-analysis

Once inputs are confirmed:

  1. Deep-dive into each reference repo/standard to establish the target state across all dimensions (deployment, security, observability, CI/CD, documentation, architecture, testing).
  2. Assess the system under review against each dimension.
  3. Produce the gap analysis with:
  4. Technology stack comparison table
  5. Architecture quality assessment (ahead / aligned / behind)
  6. Dimension gap tables (6 dimensions)
  7. Overall scorecard (star ratings)
  8. Priority actions (P0 / P1 / P2 / P3)
  9. Key decisions required

HITL Gate 2 — Gap analysis review

Present the gap analysis and ask the user to review for accuracy:

Here's the gap analysis. This is the foundation for everything that follows
— the plan, SoW, and timeline all derive from these findings. Please review
carefully:

1. **Factual accuracy** — Are any findings wrong? (e.g. "we DO have
   structured logging" or "test count is 213, not 103")
2. **Priority ratings** — Anything that should be higher or lower priority?
3. **Missing gaps** — Anything I've missed entirely?
4. **Findings you disagree with** — Any assessments that don't match reality?
5. **Key decisions** — Can you make any of the listed decisions now?
6. **Information gaps** — Are there sections where I've had to assume because
   data wasn't available? Should we collect that data before proceeding?

Corrections at this stage are cheap. The same error in the plan or SoW
will cost 5-10x more to fix because I'll need to re-derive dependent
sections.

If corrections are provided: Apply them to the gap analysis, re-present the corrected sections, and ask for re-approval before proceeding.

If information gaps are significant: Proceed to Phase 2.1 (supplement).

Wait for explicit approval before proceeding to Phase 3.

2.1 Supplement round (if needed)

If the gap analysis reveals significant unknowns (e.g. "test count unknown", "logging config unclear", "database size not documented"):

Skill: create-followup-request

Generate a structured prompt for the business user / codebase owner to collect missing technical detail. This produces a .md file with: - Section type badges (Copy file / Code review / Run and report) - Sensitive data redaction checklist - Prerequisite check - Completion checklist - Ready-to-paste LLM prompt

HITL Gate 2.1 — Supplement integration

When the supplement comes back:

  1. Update the gap analysis with confirmed evidence.
  2. Flag every finding that changed (upgraded, downgraded, or new).
  3. Re-present the changed sections to the user:
The supplement changed [N] findings in the gap analysis. Here are the
changes:

[list of changes with before/after]

Please confirm these updates are correct before I build the plan from
this revised gap analysis.

Wait for explicit approval before proceeding to Phase 3.

Phase 3 — Remediation plan

Skill: remediation-plan (or plan-work)

Build a phased remediation plan from the approved gap analysis:

  1. Phase 0 — Preconditions (access, migration, diagnostic)
  2. Phase 1 — P0 items (deployment capability)
  3. Phase 2 — P1 items (production promotion gates)
  4. Phase 3 — P2 items (operational maturity)

Each work item has: effort estimate, dependencies, exit criteria, skill reference.

Include: - Evidence checkpoints between phases - Risk register - Dependency graph (Mermaid)

HITL Gate 3 — Remediation plan review

Present the plan and ask the user to review structure, phasing, and estimates:

Here's the remediation plan, built from the approved gap analysis.

Please review:

1. **Phasing** — Does the order make sense? Should anything move between
   phases? Are preconditions correct?
2. **Work items** — Any missing? Any that shouldn't be here? Any that are
   too vague or too granular?
3. **Effort estimates** — Are the T-shirt sizes (Small/Medium/Large)
   reasonable for your team's experience with these technologies?
4. **Dependencies** — Are the internal dependency chains correct? Have I
   missed any "X must happen before Y" relationships?
5. **Risk register** — Any risks I've missed? Any likelihood/impact ratings
   that feel wrong?
6. **Exit criteria** — Would you accept these as "done" definitions?
7. **Team size** — How many engineers will work on this? (affects timeline)
8. **Target start date** — Any date in mind? (needed for illustrative timeline)

Errors in the plan will flow directly into the SoW scope, milestones,
dependencies, and timeline. Better to catch them here.

If corrections are provided: Apply them, re-present changed sections, and ask for re-approval.

Wait for explicit approval before proceeding to Phase 4.

Phase 4 — Skills summary

Skill: create-skills-summary

If engineering library skills exist, produce a skills summary:

  1. Skills used in the plan (with plan item references)
  2. Available skills not used (with rationale)
  3. Skills useful during execution
  4. Skill gaps — capabilities needed but no skill exists

HITL Gate 4 — Skills summary review

Here's the skills summary. Quick review:

1. Are the skill-to-plan-item mappings correct?
2. Any skills I've listed as "not used" that should actually be applied?
3. Do the skill gap priorities look right?

This is a lighter review — the skills summary is informational and doesn't
drive the SoW structure directly. But incorrect mappings will mislead
engineers during execution.

Wait for acknowledgement before proceeding to Phase 5.

Phase 5 — CARES and external dependencies

Skill: create-cares

Add to the remediation plan (or produce separately for the SoW):

CARES

  • Caveats — what limits accuracy (doc-based assessment, T-shirt estimates)
  • Assumptions — what must be true, with "Impact if Wrong"
  • Risks — top risks with likelihood/impact/mitigation
  • Exclusions — what's out of scope, with rationale

External dependencies

Scan every work item for references to external teams. Capture: - Owner, blocks, required by, detail - Categorise: business decisions, TDA, Central IT, data team, security

HITL Gate 5 — CARES and dependencies review

This is a critical gate — CARES and dependencies form the contractual protection in the SoW. Errors here have commercial consequences.

Here are the CARES and external dependencies. These will go directly into
the SoW as contractual language. Please review carefully:

**Caveats:**
1. Are there limits on this plan's accuracy that I haven't stated?

**Assumptions:**
2. Are any assumptions already confirmed as facts? (I'll remove them from
   assumptions and state them as facts)
3. Are any assumptions wrong? (This will change the plan)
4. Service tier — what T-level do you expect? (drives infrastructure sizing)
5. Concurrent users — can I assume [N]?

**Risks:**
6. Any risks I've missed? Any mitigations you disagree with?

**Exclusions:**
7. Any exclusions you disagree with? (e.g. "we DO need load testing")
8. Anything that should be excluded that isn't?

**External dependencies:**
9. Have I identified the correct owner for each dependency?
10. Are there external approvals or teams I've missed?
11. Are any dependencies already resolved? (I'll remove them)

Getting this wrong means the SoW either over-commits (missing exclusions)
or under-protects (missing dependencies and assumptions).

If corrections are provided: Apply them, re-present changed sections, and ask for re-approval.

Wait for explicit approval before proceeding to Phase 6.

Phase 6 — Statement of Work

Skill: create-sow

Assemble the SoW from all preceding approved documents:

  1. Background, objectives, scope
  2. CARES section
  3. External dependencies with owners
  4. Milestones aligned to plan phases
  5. Key dates for dependency owners
  6. Protective clauses (day-for-day slip, information sharing, change control)
  7. Acceptance criteria
  8. References to all source documents

HITL Gate 6 — SoW review

The SoW is the primary contractual document. Review must be thorough.

Here's the Statement of Work. This is the document that will be shared
with stakeholders for sign-off.

Please review each section:

1. **Background** — Does it accurately describe the system and context?
2. **Objectives** — Are these the right outcomes? Any missing?
3. **Scope** — Is the in-scope / out-of-scope boundary correct?
4. **CARES** — Carried forward from Gate 5. Any changes since then?
5. **Dependencies** — Owners and required-by dates correct?
6. **Milestones** — Are these the right phase boundaries? Exit criteria OK?
7. **Protective clauses** — Day-for-day slip, 5-day response SLA, change
   control — do these match your expectations?
8. **Acceptance criteria** — Would you sign off against these?
9. **Tone and language** — Appropriate for the audience?

This is the last chance to catch issues before the timeline is derived
from these milestones and dependencies.

If corrections are provided: Apply them, re-present changed sections, and ask for re-approval.

Wait for explicit approval before proceeding to Phase 7.

Phase 7 — Timeline

Skill: create-timeline

Produce the timeline document:

  1. Map effort to duration (T-shirt to days)
  2. Identify critical path from dependency graph
  3. Build Mermaid Gantt chart
  4. Define milestones (M0–M3 or as appropriate)
  5. Risk-adjusted range (optimistic / expected / pessimistic)
  6. Phase overlap and parallelisation analysis
  7. Key dates for dependency owners (illustrative calendar)

HITL Gate 7 — Timeline review

Here's the timeline with Gantt chart, critical path, and risk-adjusted
range.

Please review:

1. **Milestone dates** — Do the target weeks (M0: Week 2, M1: Week 6, etc.)
   feel reasonable?
2. **Critical path** — Does the identified critical path match your intuition
   about what will take longest?
3. **Risk-adjusted range** — Are the optimistic/expected/pessimistic scenarios
   realistic?
4. **Dependency dates** — Are the illustrative dates for external teams
   achievable? Should any be earlier?
5. **Parallelisation** — Have I correctly identified which Phase 3 items
   can start during Phase 2?

If any milestone dates seem wrong, the issue is likely in the effort
estimates or dependency chain — we may need to revisit the plan (Phase 3).

If the user identifies issues that trace back to the plan: Return to Phase 3, apply corrections, and re-derive the timeline. Do not patch the timeline without fixing the underlying plan.

Wait for explicit approval before proceeding to Phase 8.

Phase 8 — Final review

Skill: final-review

HITL Gate 8 — Final package review

All documents are complete and individually approved:

- Gap analysis: [link]
- Remediation plan: [link]
- Skills summary: [link]
- Statement of Work: [link]
- Timeline: [link]
- Clarification questions: [link] (if applicable)

Final checks before sharing with stakeholders:

1. **Cross-document consistency** — Do the plan item numbers, phase names,
   and dependency IDs match across all documents?
2. **Any final adjustments** to scope, assumptions, or timeline?
3. **Remaining unknowns** — Should I generate a clarification questions .md
   for anything still unresolved?
4. **Export needs** — Do you need the Gantt chart as a PNG for Google Docs
   or slides? (Use mermaid.live or Win+Shift+S from VS Code preview)
5. **Redaction** — Should any content be redacted before sharing externally?
   (I can use the redact-with-personas skill if needed)

Skill dependency chain

graph TD
    A[Phase 1: Gather inputs] --> G1{HITL Gate 1}
    G1 -->|Approved| B[Phase 2: gap-analysis]
    G1 -->|Corrections| A
    B --> G2{HITL Gate 2}
    G2 -->|Approved| F[Phase 3: remediation-plan]
    G2 -->|Info gaps| D[2.1: create-followup-request]
    G2 -->|Corrections| B
    D --> E[Supplement received]
    E --> G2a{HITL Gate 2.1}
    G2a -->|Approved| F
    G2a -->|Corrections| B
    F --> G3{HITL Gate 3}
    G3 -->|Approved| G[Phase 4: Skills summary]
    G3 -->|Corrections| F
    G --> G4{HITL Gate 4}
    G4 -->|Approved| H[Phase 5: CARES + dependencies]
    H --> G5{HITL Gate 5}
    G5 -->|Approved| I[Phase 6: create-sow]
    G5 -->|Corrections| H
    I --> G6{HITL Gate 6}
    G6 -->|Approved| J[Phase 7: create-timeline]
    G6 -->|Corrections| I
    J --> G7{HITL Gate 7}
    G7 -->|Approved| K[Phase 8: Final review]
    G7 -->|Plan issue| F
    G7 -->|Corrections| J
    K --> G8{HITL Gate 8}
    G8 -->|Approved| L[Ship to stakeholders]
    G8 -->|Corrections| K

    style G1 fill:#f9a825
    style G2 fill:#f9a825
    style G2a fill:#f9a825
    style G3 fill:#f9a825
    style G4 fill:#f9a825
    style G5 fill:#f9a825
    style G6 fill:#f9a825
    style G7 fill:#f9a825
    style G8 fill:#f9a825

HITL gate summary

Gate Phase What's reviewed Correction cost if skipped
G1 Inputs System description, access model, org context Low — but wrong inputs cascade everywhere
G2 Gap analysis Factual accuracy, priorities, missing gaps Medium — plan and SoW built on wrong foundation
G2.1 Supplement Updated findings from codebase evidence Medium — same as G2
G3 Plan Phasing, effort, dependencies, risks High — SoW scope, milestones, timeline all derived from plan
G4 Skills summary Skill mappings and gap priorities Low — informational document
G5 CARES + deps Assumptions, exclusions, dependency owners Very high — contractual language in SoW
G6 SoW Full contractual document Very high — stakeholder-facing, hard to retract
G7 Timeline Dates, critical path, Gantt chart High — may require plan rework if dates are wrong
G8 Final package Cross-document consistency Medium — last chance before external distribution
```

Tips

  • Don't skip HITL gates. Each gate is positioned at a point where errors compound. A wrong assumption in Phase 2 becomes a wrong work item in Phase 3, a wrong milestone in Phase 6, and a wrong date in Phase 7. Fixing the root cause in Phase 2 costs one edit. Fixing it in Phase 7 means re-deriving Phases 3, 5, 6, and 7 — easily 10x the tokens and time.
  • Keep corrections at the source. If Gate 7 (timeline) reveals a problem with effort estimates, don't patch the timeline. Go back to the plan (Phase 3), fix the estimates, get re-approval at Gate 3, then re-derive downstream.
  • Gate 4 is lightweight. The skills summary is informational. An acknowledgement (not a full review) is sufficient at Gate 4.
  • Gates 5 and 6 are the most important. CARES and the SoW are contractual. Spend the most review time here.
  • Start with documents, supplement with code. A doc-first pass identifies what's claimed. A codebase supplement confirms what's real. The delta between the two is often the most valuable finding.
  • Illustrative dates beat "TBD". Even if the start date is uncertain, pick a plausible date and note it shifts day-for-day. Stakeholders respond better to "12 Aug" than "Phase 1B start".
  • CARES protects both parties. Caveats set expectations. Assumptions create shared understanding. Risks justify contingency. Exclusions prevent scope creep.
  • The supplement prompt is a force multiplier. A well-structured prompt with redaction guidance, type badges, and completion checklists gets 10x better data than "can you send me the Dockerfile?"
  • Run the supplement round early. Gaps discovered later force expensive rework.
  • Use redact-with-personas skill before sharing externally if needed.
  • Each document links to the others via filename — keep filenames consistent.
  • Mermaid Gantt syntax: no colons in task labels, no combining crit and milestone, avoid + and & in labels.
  • If the user wants a timeline PNG, use mermaid.live or Win+Shift+S from VS Code's built-in Mermaid preview.