skraft-difficulty-routing

name	skraft-difficulty-routing
description	Use at pipeline start to detect an upstream HVE backlog/sprint handoff (entry-point skip), and at DISCOVER exit to evaluate the difficulty axis, validate immutable invariants, and persist to state.json

SKRAFT Difficulty Routing

Evaluate two orthogonal axes around the DISCOVER phase. The Entry Point axis is evaluated at pipeline start (Phase 0) — before DISCOVER — so the orchestrator can skip DISCOVER when an upstream HVE handoff already provides the backlog and the sprint. The Difficulty axis is evaluated at the exit of DISCOVER (or, when DISCOVER is skipped, immediately after ingestion at pipeline start). The orchestrator invokes this skill, then persists the outcome to state.json.

The two orthogonal axes

1. Entry Point — which phases run

Determine whether any phase can be skipped because an upstream artefact already satisfies its checklist. In v1 this targets a single case: DISCOVER is skipped when an HVE handoff already provides a triaged backlog and a calculated sprint, so SKRAFT does not re-triage issues or re-propose a sprint. Persisted in state.json::entryPoint. Default: skipPhases is empty — every phase runs.

Detection — HVE handoff signals

At pipeline start, look for either form of HVE output (both may be present):

Form	Signal	handoffSource
A — GitHub issues already triaged + scheduled	Open issues already carry triage labels (type/*, priority P0–P3, effort) and a milestone or sprint/iteration assignment, with no pending DISCOVER artefacts	hve-github
B — ADO sprint artefact	A sprint-plan.md exists under .copilot-tracking/workitems/sprint/{iteration}/ (HVE ADO backlog manager output) with a capacity/coverage table	hve-ado
B — Jira sprint artefact	A planned-sprint artefact exists under .copilot-tracking/jira-issues/** with an Epic/Feature/Story hierarchy and a sprint assignment	hve-jira

A handoff is confirmed only when the signal carries BOTH a backlog hierarchy (Epic/Feature/Story or triaged issues) AND a sprint/iteration scope. A backlog with no sprint, or a sprint with no triaged items, is NOT a complete handoff — DISCOVER runs normally.

Confirmation gate

Detection never auto-skips. Surface the detected handoff to the user once and require explicit acknowledgement before recording the skip:

🔎 HVE handoff detected
Source: {handoffSource}
Backlog: {n} items (Epic/Feature/Story | triaged issues)
Sprint: {sprint/iteration name} — capacity {value}
Artefacts: {handoffArtifacts}

SKRAFT can SKIP its DISCOVER phase (no re-triage, no second sprint proposal)
and ingest this handoff directly into DISCUSS. Proceed? [skip DISCOVER | run DISCOVER anyway]

If the user chooses run DISCOVER anyway, leave entryPoint.skipPhases empty and proceed normally. If the user chooses skip DISCOVER, set entryPoint = { skipPhases: ["DISCOVER"], handoffSource, handoffArtifacts } and run the ingestion protocol below.

Ingestion protocol (only when DISCOVER is skipped)

The DISCUSS agent (backlog-planner) requires DISCOVER artefacts (research/{date}/triage-*.md, optionally sprint-proposal.md). When DISCOVER is skipped, this skill maps the HVE handoff into those expected artefacts — it does NOT re-triage or re-prioritize:

1. Map the backlog → research/{date}/triage-ingest-{date}.md. For each HVE work item / triaged issue, copy across: title, type, the HVE priority (do NOT recompute it), effort if present, and the source reference (work item ID or issue number). Add a header noting source: {handoffSource} and ingested: true so downstream readers know triage was inherited, not produced.
2. Map the sprint → research/{date}/sprint-proposal.md. Copy the HVE sprint scope verbatim: the ordered list of items in the sprint, the capacity figure, and any dependency ordering. Do NOT re-run capacity×0.7, MoSCoW, or the P0 override — the sprint is inherited as-is. Add a note: Sprint inherited from {handoffSource}; not recomputed by SKRAFT.
3. Sanitize internal tracking paths per HVE convention (strip .copilot-tracking/ absolute paths, keep work item / issue IDs and standards references).
4. Record both written paths in state.json::phaseArtifacts.DISCOVER and append the handoff source paths to state.json::entryPoint.handoffArtifacts.

The immutable invariants below still apply to the ingested artefacts (dated HVE paths, schema compliance, no secrets).

2. Difficulty Tier — DELIVER execution model

Persisted in state.json::difficulty. Drives whether the software-engineer agent works inline or dispatches sub-agents and intermediate artifacts:

Difficulty	DELIVER execution model
simple	Inline TDD cycle, single commit per scenario
medium	Inline TDD cycle, multi-commit per scenario, walking skeleton
medium-hard	Dispatch sub-agent per Gherkin scenario, write intermediate plan
challenging	Dispatch sub-agent per scenario, write spike notes under details/{date}/, multiple review passes

Difficulty is assessed once at DISCOVER exit and never re-evaluated mid-pipeline.

Immutable invariants (always blocking)

These hold on every run. Nothing downgrades them:

• TDD mandatory — at minimum Red-Green; no production code without a prior failing test.
• Clean Architecture layer boundaries — Domain depends on neither Application nor Infrastructure.
• Test integrity — no test may be deleted or disabled to pass GREEN.
• state.json schema compliance — every turn writes a valid state document.
• HVE dated paths — research/{date}/, details/{date}/, changes/{date}/, reviews/{date}/ (ADRs are project-global in docs/adr/, not a per-run dated path).
• Reviewers are read-only — reviewers write exclusively to reviews/{date}/.
• No secrets or credentials committed.

Gate enforcement

Every gate blocks, and the thresholds are permanent. skraft-quality-bar owns both -- this skill does not restate them. There is no advisory level, no warning level, and no override.

Output protocol

After evaluation, the orchestrator must:

1. Write state.json::entryPoint (including skipPhases, handoffSource, handoffArtifacts) and state.json::difficulty (per-work-item).
2. When entryPoint.skipPhases contains "DISCOVER", confirm the ingestion artefacts (research/{date}/triage-ingest-{date}.md, research/{date}/sprint-proposal.md) exist before setting currentPhase to DISCUSS.
3. Surface the routing decision in the next user-facing message using an emoji checklist (✅ chosen axis values, 🛡️ active invariants, ⏭️ any skipped phase with its handoff source).
4. Proceed to DISCUSS once the user acknowledges the routing summary.