Dia Guide

V-Model Workflow Guide

What this skill does (and does not do)

/dia-guide is the read-only orientation layer of DIA. It:

• Reads BACKLOG.md, the latest HANDOFFS.md entry, and git

state when the user invokes it

• Recommends the next phase skill in plain text
• Audits whether the last handoff carries the binding fields

(triage:, triage_kind:, epic:, feature:)

• Runs the Closing Handoff after a green /security-audit
• Owns two narrow CRUD moments at workflow boundaries that no single

phase skill covers: (a) the post-/reverse-engineering item promotion (described below), and (b) the item-start branch creation when the user enters at A/B/C from a fresh repo

What the guide does NOT do:

• It does not perform artifact triage. Triage lives in every phase

skill's MANDATORY Phase 0 block. See skills/project-conventions/references/graph-invariants.md, section "Artifact triage at entry point".

• It does not enforce the plan gate. The plan gate lives in

/coding Phase 3a as the "Plan Coverage Gate (binding, runs before Status flips to Active)". /coding runs the gate; the guide only reads the result.

• It does not run /consistency-check mode A at phase boundaries.

Each phase skill runs mode A in its own handoff ritual. Mode B fires from the Closing Handoff, see below.

• It does not call other skills. It recommends; the user invokes.

Item-start branch creation

When the user picks entry-point A, B, or C in the hybrid entry-point detection (see "Start: Determine Phase" below), the guide creates a fresh feature branch from the configured source branch before the phase skill takes over. The phase skill itself does not own this because the branch must exist before the first artifact is written.

Steps:

1. Read .dia/config.toml. Extract the source_branch

(default develop) and the mode. If the file is missing, fall back to develop and treat the mode as git-only.

1. Slug input. Ask the user (single AskUserQuestion, short

plain-text "Other" slot) for a short kebab-case slug describing the item. The slug is provisional. It becomes the suffix of the feature branch name. Example: auto-save-on-input.

1. Branch creation.

``bash git fetch origin --quiet || true git checkout git pull --ff-only origin 2>/dev/null || true git checkout -b feature/ `` If the branch already exists, switch to it and warn the user. Do not overwrite work.

1. Mode-aware GitHub side-effect. If mode = "github-sync" and

the user has an existing GitHub issue tracking this item, the guide reminds the user to assign themselves on GitHub so that flow.py sync-status can mirror the assignee into the BACKLOG Claim column once the item gets a real ID. The guide does not create an issue at this stage; the phase skill that first writes a backlog row (typically /business-analysis or /requirements-engineering) calls flow.py create-issue once the ID is known.

1. Hand-off. Print the branch name to the user, then recommend

the relevant phase skill: A -> /business-analysis, B -> /requirements-engineering, C -> /architecture. The phase skill takes over.

Branch rename after RE: when /requirements-engineering finishes and the EPIC ID is known, the user (or /dia-guide on a later invocation) can run

python3 tools/github-integration/flow.py promote-to-epic --item EPIC-NN --rename-branch

to retitle the parent issue, create sub-issues, and rename the branch from feature/ to feature/epic-NN-. The guide does not run this automatically; the user invokes it via the RE handoff or directly.

Post-reverse-engineering item promotion (the only CRUD moment)

/reverse-engineering finishes with a backlog seed: 20+ items at Status: Backlog, Source: REV, Notes: anticipated on a single feature/reverse-engineer- branch. The Status column uses the GitHub-aligned vocabulary; the "anticipated" flavour is recorded in the Notes column so the user can filter for it during triage. Per-item branches and per-item GitHub issues kick in only after a user-driven triage: which seed items become real backlog candidates? /reverse-engineering explicitly defers this step to the guide (see RE's Pre-Phase 0).

This is the only place where the guide writes. It is a multi-item user interaction at a workflow boundary that no single phase skill covers. The user drives the triage; the guide executes the per-item operations.

Steps:

1. Read BACKLOG.md, list items with

Status: Backlog, Source: REV whose Notes column contains anticipated.

1. AskUserQuestion: which items should be promoted now (vs. left in

Backlog with the anticipated note for later)?

1. For each promoted item:

`` python3 ${DIA_PLUGIN_ROOT:-.}/tools/github-integration/flow.py create-issue --item git tag -a /reverse-engineered -m "Item promoted from /reverse-engineering" ``

1. Update BACKLOG row: Status -> Ready (or In Progress if the

item already ships and only needs the inventory recorded). Remove the anticipated note from the Notes column.

1. Recommend the next skill: typically /business-analysis to

validate the BA draft, or /coding for items that already ship and just need the inventory recorded.

Handoff state audit (read-only, on user invocation)

When the user invokes /dia-guide after a phase skill has finished, the guide reads the team-workflow surface and reports any drift between artifact state and collaboration state. It does NOT write, fix, or tag. It surfaces, the user decides.

Audited surfaces (full reference: skills/project-conventions/references/team-workflow.md):

1. Branch. Is the current branch on an item-branch (per

team-workflow.md schema)? If not, surface a warning.

1. Phase tag. Did the just-finished phase set its

/-done tag via tools/github-integration/flow.py tag-phase? Each phase skill is responsible for setting its own tag during its handoff ritual. If missing, the guide names the phase skill that should re-run its handoff ritual.

1. Backlog row. Does the BACKLOG row's status reflect the phase

progress (Building during BA -> RE -> Coding, Released only after merge)? Discrepancies indicate the phase skill's handoff ritual did not write the row before the phase-end commit.

1. GitHub issue. Does the issue exist and carry the right phase

label and ticked checklist? Each phase skill's flow.py tag-phase call invokes update_issue_after_tag internally to keep the issue in sync. The guide only reads flow.py status --item and reports the snapshot.

1. HANDOFFS entry. Does the latest entry have triage:,

triage_kind:, and (for IMP/FIX) epic: + feature:? Missing fields are flagged with the responsible phase skill named.

The guide reports findings in plain text and recommends the next step. It does not auto-fix, does not append to METRICS, does not tag, and does not call other skills. METRICS is written by phase skills directly; the guide only reads it.

Feature-complete read (before release)

When the user asks "is this item ready for release?", the guide reads the phase tags and reports. No tagging, no PR transition, no skill invocation.

Audit:

1. Verify all required phase tags exist for the active item:

• /code-done (always)
• /test-done (always)
• /sec-done (when item touches security-relevant surface; legacy /audit-done is also accepted)

1. Run flow.py status --item and show the user the result.

1. Report in plain text:

``` Item '' phase status:

• code-done: yes/no
• test-done: yes/no
• sec-done: yes/no/n-a

Verdict: feature-complete | missing tags: ```

If a tag is missing, the guide names the responsible phase skill so the user can re-run it. If feature-complete, the user can mark the PR ready (flow.py ready-for-review --item ) and invoke their private release skill themselves. The guide does neither.

---

This skill is the navigation layer. Each phase builds on the previous one and produces artifacts as input for the next phase. All phases follow the conventions from /project-conventions.

Workflow Overview

Phase 0 (brownfield only): /reverse-engineering REVERSE WALK
 Input: existing codebase + documentation (backwards
 Output: plan-context.md, ADRs (Inferred), up the V)
 arc42 (Snapshot), FEATURE-*.md (Observed),
 BA-{PROJECT}.md (Draft), backlog seed
 |
 v (forward walk starts here)
Phase 1: /business-analysis DESIGN
 Output: _devprocess/analysis/BA-{PROJECT}.md (left side
 | of the V)
 v
Phase 2: /requirements-engineering
 Input: BA document
 Output: Epics, Features, architect-handoff.md
 |
 v
Phase 3: /architecture
 Input: Features, ASRs, NFRs
 Output: ADRs, arc42, plan-context.md
 |
 v
Phase 4: /coding IMPLEMENTATION
 Input: plan-context.md + ADRs + Features (bottom of the V)
 Action: Load context, critical review,
 brief the Default agent (task breakdown,
 optional TDD, debugging protocol,
 verification gate), write artifacts back
 |
 v
Phase 5: /testing VERIFICATION
 Input: Implemented codebase + Features (right side
 Output: Unit + integration tests, fix-loop of the V)
 |
 v
Phase 6: /security-audit
 Input: Implemented codebase
 Output: Security report + remediation, fix-loop
 |
 v
Closing Handoff (not a phase)
 Input: Green security audit
 Output: /consistency-check mode B verdict + release-to-ba
 HANDOFFS template; user can run their private release skill

Phase Transitions (read-only audit)

When the user invokes /dia-guide between phases, the guide reads project state and surfaces the next step. The guide does not drive or launch phase skills; phase skills are autonomous and own their own handoff ritual. The guide observes:

1. Reads the latest entry in _devprocess/context/HANDOFFS.md

(artifact report, triage IDs, release-readiness markers)

1. Reports the recommended next step in plain text and names the

skill to invoke (e.g. "Recommended next: /coding")

1. The user invokes the next phase skill themselves; the guide does

not call other skills

The guide does not loop, does not auto-advance, and does not block. Every phase transition is a separate user action. The guide is re-invoked whenever the user wants the next-step audit again.

When a phase-skill is invoked directly (without /dia-guide): The Handoff Ritual still runs, and the handoff context is still written to _devprocess/context/HANDOFFS.md. The user can then manually start the next skill, which will pick up the handoff entry.

Handoff entry format (binding)

Every new handoff entry in _devprocess/context/HANDOFFS.md starts with a short header block that carries the artifact triage from Phase 0. The next skill does not need to re-ask the triage question.

## {skill-from}-to-{skill-to} {YYYY-MM-DD}

triage: FEAT-01-03         # or IMP-007 / FIX-012 / ADR-04
triage_kind: feature             # one of: feature | improvement | fix | adr
epic: EPIC-01                   # mandatory for IMP/FIX; recommended otherwise
feature: FEAT-01-03         # mandatory for IMP/FIX

... (phase-specific fields, e.g. NFR summary, open questions, ...)

Rule: a skill that reads a handoff entry and finds a triage ID uses it as the Phase-0 assignment and skips the triage question. If the field is missing, the skill falls back to normal Phase-0 logic (derive from prompt, ask if needed).

Exception: the very first handoff entry in a greenfield project (e.g. /business-analysis to /requirements-engineering without an existing feature) MAY carry triage: new-feature-pending. The concrete FEATURE ID is then assigned by /requirements-engineering and written into the next handoff entry.

Ensure project structure exists

Before a phase starts, check whether the directory structure exists. If not, initialize it per /project-conventions:

mkdir -p _devprocess/{analysis/sources,requirements/{epics,features,fixes,improvements,handoff},architecture,rules,implementation/plans,context}
mkdir -p src docs scripts memory
touch _devprocess/context/HANDOFFS.md

For _devprocess/context/BACKLOG.md, do not touch an empty file. Seed it from skills/requirements-engineering/templates/BACKLOG-TEMPLATE.md with the project name, an empty dashboard, and the placeholder sections. Every phase skill updates this file per the binding format.

For _devprocess/rules/, seed technical.md from skills/architecture/templates/RULES-TECHNICAL-TEMPLATE.md. Add design.md only if the project has UI surface, seeded from RULES-DESIGN-TEMPLATE.md. Add domain.md if the project has business-domain rules, seeded from RULES-DOMAIN-TEMPLATE.md.

For src/ARCHITECTURE.map, seed from skills/architecture/templates/ARCHITECTURE-MAP-TEMPLATE.md with empty rows. /architecture and /coding populate it as entry-points appear.

Start: Determine Phase

Before asking the user, the guide runs a hybrid entry-point detection (added 2026-04-20): it scans the project, diagnoses the graph state, and formulates a recommendation. The user keeps the override.

Step 1: Scan + recommend

1. Detect the project root convention (_devprocess/ or docs/).
2. Run /consistency-check in Mode A (syntactic). The result is the

current Graph-Health snapshot.

1. Infer the likely entry point from the snapshot:

| Observation | Recommended entry | | ------------------------------------------------------------- | ------------------------------------------ | | No V-Model artifacts at all, empty repo or pure greenfield | /business-analysis (Project-BA) | | Code exists, no _devprocess/analysis/BA-*.md, no FEATUREs | /reverse-engineering | | Project-BA exists as Draft, not yet validated | /business-analysis Validation Mode | | Project-BA validated, user wants to start a new epic / feature | /business-analysis (Item-BA) | | Project-BA validated and Item-BA exists, no EPIC/FEAT yet | /requirements-engineering | | Features exist, no ADRs or plan-context.md | /architecture | | plan-context.md exists, no recent code changes | /coding | | Coding done, no test coverage / failing tests | /testing | | Tests green, no security audit | /security-audit | | Everything closed, release pending | Closing Handoff (/consistency-check mode B + /release if configured) | | Graph-Health shows many orphans or dead links | /consistency-check + Cleanup first |

Step 2: Present recommendation + alternatives

Show the user one AskUserQuestion with the recommendation as the first option and the manual list as alternatives:

Graph-State (letzter Check {date}):
- Epics {n}, Features {n} (Released {a}, Building {b}, Planned {c}, Candidates {d}),
 ADRs {n}, FIX/IMPs {n}, offene Luecken {n}.

Empfehlung basierend auf dem Graph-State: {recommended entry}

Oder du waehlst manuell aus:
A0 /reverse-engineering (brownfield)
A /business-analysis (BA von Beginn)
B /requirements-engineering
C /architecture
D /coding
E /testing
F /security-audit
G Closing Handoff (Audit ist gruen, Cycle abschliessen)
H /consistency-check (nur Graph-Pflege)
I Orientierungs-Interview (helfe beim Entscheiden)

If the user picks the recommended option or says "ok/go/next", start that phase. If the user picks a different option, start that one. If the user wants an interview, ask short follow-up questions to refine the recommendation.

Step 3: Phase-Entry mit Konsistenz-Hinweis

Beim Start der gewaehlten Phase zeigt der Guide eventuelle Konsistenz-Luecken aus /consistency-check, die fuer die Phase relevant sind. Beispiel: vor /architecture-Start "Du hast 3 Features ohne Epic-Parent, das sollten wir vorher klaeren, willst du /consistency-check auto-fixes laufen lassen?"

Recommended next step per phase

These are the standard recommendations the guide surfaces when a phase is complete. The guide does not invoke the next skill; it prints t

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pssah4
• Source: pssah4/digital-innovation-agents
• License: MIT
• Homepage: https://pssah4.github.io/digital-innovation-agents/

Install and usage instructions live in the source repository linked above.