Skill: Align Planning

Purpose

Keep project execution aligned with higher-level planning by running a post-task alignment loop: traceback from completed work to strategy, detect drift, and produce top-down recalibration recommendations.

---

Core Objective

Primary Goal: Produce an actionable Planning Alignment Report after task completion, with clear drift classification and prioritized recalibration actions.

Success Criteria (ALL must be met):

1. ✅ Traceback completed: The completed task is traced through applicable project layers for the selected mode
2. ✅ Drift classified: All detected misalignments use the planning drift model (goal, requirement, roadmap, priority), with impact scope and root cause per item
3. ✅ Calibration produced: A top-down recalibration recommendation list is provided, including next tasks
4. ✅ Report persisted: Planning Alignment Report is written to the agreed path
5. ✅ Evidence readiness assessed: Missing or weak documentation is explicitly scored and reflected in confidence
6. ✅ Unsafe writes avoided: If mapping is uncertain or updates are destructive, user confirmation is requested before proposing file-level changes

Acceptance Test: Can a teammate read the report and immediately understand whether planning is still aligned with execution, what drift exists, what to do next, and why?

---

Scope Boundaries

This skill handles:

• Post-task alignment assessment
• Bottom-up traceback across project layers
• Drift detection, impact analysis, and root cause labeling
• Top-down recalibration suggestions
• Next-task recommendations with priority hints
• Evidence readiness assessment and graceful degradation when planning documents are incomplete

This skill does NOT handle:

• Rewriting requirements from scratch (use analyze-requirements)
• Redesigning architecture (use design-solution)
• Architecture vs code compliance (use align-architecture)
• Creating a new roadmap or milestone system from scratch
• Implementing code changes
• Team retrospective facilitation ("what went well / poorly")

Handoff point: After the report is produced and reviewed, hand off to the relevant skill by issue type (requirements, architecture design, planning, architecture compliance, or repair loop).

---

Use Cases

• Post-task checkpoint: Validate alignment after any completed ticket
• Milestone closure review: Run full alignment before marking a milestone complete
• Release readiness: Detect planning drift before a release cut
• Scope-shift diagnosis: Investigate whether recent work still supports current goals
• Backlog reprioritization input: Generate evidence-backed next-task ordering signals

---

Orchestration Guidance

Scenario	Recommended Sequence
Routine task completed	align-planning (Lightweight)
Milestone or release gate	align-planning (Full) → then align-architecture
Planning drift suspected	align-planning
Design vs code compliance needed	align-architecture (run after align-planning when planning is also in question)

Run align-planning first when planning layer alignment is uncertain; run align-architecture after planning alignment for architecture vs code verification.

---

Behavior

Agent Prompt Contract

At execution start, follow this instruction contract:

You are responsible for planning alignment.

When a task is completed, perform traceback analysis to ensure planning
(goals, requirements, milestones, roadmap) is aligned with execution,
and produce a structured Planning Alignment Report.

Interaction Policy

• Defaults: Mode from context (lightweight unless release/milestone/epic); docs root from workspace
• Choice options: Mode override [lightweight][full] when user prefers
• Confirm: Before file-level change proposals; before proceeding when mapping is uncertain (NeedsMappingConfirmation)

Phase 0: Mode and Context Resolution

1. Resolve mode with deterministic policy:
   • If user explicitly sets mode, use it
   • Else if context contains release, milestone-closed, or epic-done, use Full Alignment Mode
   • Else use Lightweight Mode
2. Resolve document paths:
   • Default mapping assumes project-documentation-template layout
   • Apply user path mapping overrides when provided
   • Optional discovery: If user provides no path mapping and default layout does not match, run document structure discovery (e.g. scan docs/, docs/requirements/, docs/roadmap*, *.md at repo root) or suggest discover-docs-norms to establish paths; report assumed mapping and ask for confirmation if ambiguous
3. Confirm minimum context:
   • Completed task summary
   • At least one traceability anchor (requirement ID, roadmap item, milestone reference, or equivalent)

Phase 0.5: Evidence Readiness Assessment

Assess evidence quality before traceback:

• strong: canonical docs exist for all required layers in selected mode
• weak: partial docs exist, but at least one required layer depends on secondary evidence (issues/PR/commit notes)
• missing: critical layers unavailable; traceback cannot produce reliable drift typing

Rules:

1. Missing docs must not silently pass as aligned.
2. Use secondary evidence only when canonical docs are missing, and label it explicitly.
3. Confidence in conclusions must be adjusted by readiness level:
   • strong -> high confidence
   • weak -> medium confidence
   • missing -> low confidence or blocked

Mode Definitions

• Lightweight Mode: Task Backlog → Roadmap → Requirements
• Full Alignment Mode: Task Backlog → Roadmap → Milestones → Requirements → Project Goals

This skill covers the planning layer only. Architecture vs code compliance is handled by align-architecture.

Phase 1: Traceback (Bottom-Up)

1. Identify completed task intent, output, and target outcome
2. Walk upward through selected layers and record per-layer alignment status:
   • aligned | partial | misaligned | unknown
3. Capture supporting evidence for each status
4. If critical mapping is missing, enter NeedsMappingConfirmation:
   • List missing links
   • Offer 1-3 candidate mappings with rationale
   • Request user confirmation before continuing
   • If unresolved, output blocked report with required minimum inputs
5. If readiness is weak or missing, annotate per-layer evidence source:
   • canonical (project docs)
   • secondary (issue/PR/commit context)
   • none

Phase 2: Drift Detection

Classify each drift item as (planning layer only):

• Goal Drift: Work no longer supports current project objective
• Requirement Drift: Requirement changed, deprecated, or already superseded
• Roadmap Drift: Sequencing or roadmap assumptions changed
• Priority Drift: Priority is stale relative to current business direction

For implementation-vs-design drift, hand off to align-architecture.

For each item, output:

• Type
• Impact Scope
• Root Cause
• Severity (low | medium | high)

Phase 3: Calibration (Top-Down)

1. Re-derive priority from top layers downward (Goals → Requirements → Milestones → Roadmap → Backlog)
2. Produce recalibration actions:
   • Priority adjustments
   • Sequence changes
   • Dependency corrections
   • Follow-up analysis handoffs
3. Recommend next tasks with rationale and urgency window
4. If suggesting edits to canonical planning docs, request explicit confirmation before generating file-level change proposals

Phase 4: Persist Report

Write report to:

• Path resolved from project norms (docs/ARTIFACT_NORMS.md or .ai-cortex/artifact-norms.yaml)
• Default: docs/calibration/planning-alignment.md (overwrite unless snapshot explicitly requested)
• Or user-specified path

Report must include a machine-readable drift block (YAML or JSON) in addition to human-readable sections. Report must also include an evidence readiness block and explicit confidence level.

---

Input & Output

Input

• Completed task description and outcome
• Optional mode override (lightweight | full)
• Optional document root/path mapping
• Optional context: release/milestone/epic markers

Output

Planning Alignment Report Template

# Planning Alignment Report: <task title>

**Date:** YYYY-MM-DD
**Mode:** Lightweight | Full
**Status:** aligned | partial | misaligned | blocked
**Confidence:** high | medium | low

## Completed Task
- Summary:
- Outcome:

## Traceback Path
Task Backlog -> Roadmap -> Milestones -> Requirements -> Project Goals

## Evidence Readiness
- Readiness: strong | weak | missing
- Missing Layers:
- Secondary Sources Used:

## Alignment Status
- Goal Alignment:
- Requirement Alignment:
- Milestone Alignment:
- Roadmap Alignment:

## Drift Detected
- Type:
  Impact Scope:
  Root Cause:
  Severity:

## Impact Analysis
- Delivery impact:
- Technical impact:
- Planning impact:

## Calibration Suggestions
1.
2.
3.

## Recommended Next Tasks
1.
2.
3.

## Machine-Readable Drift

    drifts:
      - driftType: "Requirement Drift"
        severity: "medium"
        owner: "product-team"
        dueWindow: "next-sprint"
        impactScope: "Search filter acceptance criteria"
        rootCause: "Requirement updated to include keyboard navigation; task covered only click interactions"
    evidence:
      readiness: "weak"
      confidence: "medium"
      missingLayers:
        - "docs/requirements-planning/search-improvements.md"
      secondarySources:
        - "PR#142"
        - "commit:abc1234"

---

Restrictions

Hard Boundaries

• Do NOT invent traceability links when evidence is missing
• Do NOT claim high confidence when readiness is weak or missing
• Do NOT silently modify planning truth sources (goals, requirements, milestones, roadmap) without explicit user approval
• Do NOT collapse drift categories into a generic "misalignment" bucket; keep typed drift outputs (goal, requirement, roadmap, priority)
• Do NOT skip layer checks in Full mode unless the layer is truly unavailable (mark as unknown and explain)
• Do NOT present recommendations without rationale tied to traceback evidence

Skill Boundaries (Avoid Overlap)

Do NOT do these (other skills handle them):

• Requirements redefinition workflow → analyze-requirements
• Architecture option design workflow → design-solution
• Repo-level onboarding → review-codebase, generate-standard-readme, generate-agent-entry (run in sequence as needed)
• Automated test-and-fix loop execution → run-repair-loop

When to stop and hand off:

• Requirements are invalid or contradictory → hand off to analyze-requirements
• Architecture design conflict is primary blocker → hand off to design-solution
• Architecture vs code compliance check needed → hand off to align-architecture
• Report indicates active implementation defects requiring repair → suggest run-repair-loop

---

Self-Check

Core Success Criteria (ALL must be met)

• Traceback completed for selected mode
• Drift items typed using the four-category planning model
• Each drift has impact scope and root cause
• Top-down calibration actions provided
• Report persisted to agreed path
• Evidence readiness level and confidence are explicitly reported
• Confirmation requested where mapping or write safety is uncertain

Process Quality Checks

• Mode selection followed deterministic policy
• Mapping uncertainty triggered NeedsMappingConfirmation
• Canonical vs secondary evidence is clearly separated
• Evidence references are present for each alignment status
• Recommendations are prioritized and time-bounded
• Handoffs to adjacent skills are explicit when needed

Acceptance Test

Can a teammate execute the top 1-3 recommendations without additional clarification and explain why they are highest priority?

If NO: report is incomplete; refine traceback evidence and recalibration details.

If YES: report is complete; proceed to handoff or execution planning.

---

Examples

Example 1: Lightweight Mode (Routine Task)

Context: Completed task updates search filter UI behavior.

Mode resolution: No explicit override, no release/milestone/epic marker → Lightweight.

Traceback:

• Task aligns with roadmap item search-improvements-q2
• Requirement still valid, but acceptance criteria changed last week
• Evidence readiness is strong because requirement and roadmap docs are both canonical and current

Drift:

• Requirement Drift (medium): Requirement wording changed to include keyboard navigation; completed task only covers click interactions

Calibration:

1. Add follow-up task for keyboard navigation
2. Move accessibility acceptance check before merging related UI tasks
3. Reorder backlog items to unblock regression testing

Example 2: Full Mode (Milestone Closure)

Context: Milestone tagged milestone-closed after API gateway auth rollout.

Mode resolution: Marker hit → Full.

Traceback:

• Roadmap and milestone mapping valid
• Goal and requirements still valid
• Evidence readiness is strong; canonical docs exist for all planning layers

Drift:

• Priority Drift (high): Migration work was not promoted in backlog

Calibration:

1. Insert migration epic into current sprint planning
2. Defer non-critical gateway enhancements
3. Recommend running align-architecture for architecture vs code compliance check

Example 3: Edge Case (Blocked Mapping)

Context: Completed task has no requirement ID or roadmap link.

Behavior:

1. Enter NeedsMappingConfirmation
2. Present candidate mappings with confidence notes
3. Ask user to confirm mapping before drift classification

Result:

• If user confirms: continue normal flow
• If not confirmed: output blocked report with missing fields checklist
• Confidence remains low until canonical mappings are established