align-planning

# Skill: Coordinated Planning

Purpose

Through a post-task adjustment loop, keep project execution aligned with higher-level planning: trace back from completed work to strategy, detect deviations, and generate top-down recalibration recommendations.

Core Objective

Primary Objective: After task completion, generate an actionable planning adjustment report that includes clear deviation classifications and prioritized recalibration actions.

Success Criteria(all requirements must be met):

✅ Track Completed: Track completed tasks through the applicable project layers of the selected mode
✅ Drift Classification: All detected deviations use the planning drift model (goals, requirements, roadmap, priorities), and each item has impact scope and root cause
✅ Generate Calibration: Provide a top-down list of recalibration recommendations, including follow-up tasks
✅ Report Persistence: The planning alignment report is written to the agreed path
✅ Assess Evidence Readiness: Explicitly score missing or weak documentation and reflect it in confidence
✅ Avoid Unsafe Writes: If mapping is uncertain or updates are destructive, request user confirmation before proposing file-level changes

AcceptanceTest: Can a teammate read the report and immediately understand whether the plan is still aligned with execution, what deviations exist, what to do next, and why?

Scope Boundaries (Scope Boundaries)

This skill is responsible for：

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

This skill is not responsible for：

Rewriting requirements from scratch (use "Analyze Requirements")
Redesigning the architecture (use "Design Solution")
Architecture and code compliance (use "align-architecture")
Creating a new roadmap or milestone system from scratch
Implementing code changes
Team retrospective facilitation ("what went well/what went poorly")

Handoff Point: After report production and review, hand off to the relevant skill by issue type (requirements, architecture design, planning, architecture compliance, or fix loop).

Use Cases (Use Cases)

Post-task checkpoint: Verify alignment after completing any task
Milestone closure review: Run full alignment before marking a milestone complete
Release preparation: Detect planning deviations before release cut
Scope shift diagnosis: Investigate whether recent work still supports the current goals
Backlog reordering input: Generate evidence-backed next task ordering signals

Orchestration Guidance

Scenario	Recommended Order
Daily task completion	`align-planning`(lightweight)
Milestone or release gate	`align-planning`(Full) → then`align-architecture`
Planning drift suspected	`对齐规划`
Design and code compliance required	`align-architecture` (when planning is also problematic, run after `align-planning` )

When planning-layer alignment is uncertain, run "align-planning" first; run "align-architecture" after aligning the plan architecture with code verification.

Behavior (behavior)

Phase 0: Norms Resolution (new in v1.4)

Implement per §8.2 / §8.3 / §8.5 of specs/artifact-contract.md §8 Runtime Norms Resolution Protocol : read the project specification; if it declares planning-alignment for artifact_type path_pattern, use the project value; otherwise fall through to the skill default (docs/calibration/planning-alignment.md). This skill isfixed-path governance output, using only the path_pattern override mechanism.

Agent immediate contract

At the start of execution, follow the instruction contract below:

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 (interaction) policy

Default: mode from context (轻量级, unless release/milestone/epic); document root in the workspace
Select option: when the user prefers, mode overrides "[lightweight][full]"
Confirm: before file-level change suggestions; before continuing when mapping is uncertain (NeedsMappingConfirmation)

Phase 0: Mode and context resolution

Resolution mode with deterministic policy:
- If the user explicitly sets the mode, use it
- Otherwise, if the context contains "release", "milestone close", or "epic-done", use full alignment mode
- Otherwise uselightweight mode 2. Resolve document paths:
- Default mapping uses the project-document-template layout
- If provided, apply user path mapping overrides
- Optional discovery: if the user did not provide a path mapping and the default layout does not match, run document structure discovery (e.g., scan at the repository rootdocs/、docs/需求/、docs/路线图*、*.md) or suggestdiscover-docs-normsto establish paths; report the assumed mapping and ask for confirmation if it is unclear
Confirm the 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 backtracking:

Strong: specification documents exist for all required layers in the selected mode
Weak: partial documents exist, but at least one required layer relies on auxiliary evidence (issues/PRs/commit notes)
Missing: critical layers are unavailable; backtracking cannot produce reliable drift types

Rules:

Missing documents must not be silently passed through alignment.
Use auxiliary evidence only when specification documents are missing, and mark it explicitly. 3. The confidence of conclusions must be adjusted according to readiness:
- 强 -> high confidence
- 弱 -> medium confidence
- 失踪 -> low confidence or blocked

Mode definitions

Lightweight mode: Task backlog → roadmap → requirements
Full alignment mode: Task backlog → roadmap → milestones → requirements → project goals

This skill only covers theplanning layer. Architecture and code compliance are handled by "align-architecture".

Phase 1: Traceback (bottom-up)

Identify the completed task's intent, outputs, and target outcomes
Traverse the selected layers upward and record the alignment status of each layer:
- 对齐 | 部分 | 错位 | 未知
Obtain supporting evidence for each status
If a critical mapping is missing, enter "NeedsMappingConfirmation":
- List the missing links
- Provide 1-3 candidate mappings with rationale
- Request user confirmation before continuing
- If unresolved, output a blocking report with the minimum required input
If readiness is "weak" or "missing", annotate the evidence source for each layer:
- canonical(project documentation)
- 次要(issue/PR/commit context)
- 无

Phase 2: Drift detection

Classify each drift item as (planning layer only):

Goal drift: the work no longer supports the current project goals
Requirement drift: the requirement has changed, been deprecated, or been superseded
Roadmap drift: sequencing or roadmap assumptions have changed
Priority drift: the priority is outdated relative to the current business direction

For deviations between implementation and design, hand off to "align-architecture".

For each item, output:

类型
影响范围 - "root cause" - "severity" ("low" | "medium" | "high")

Phase 3: Calibration (top-down)

1. Re-derive priorities from the top level downward (goals → requirements → milestones → roadmap → backlog) 2. Generate recalibration actions:

Priority adjustment
Order change
Dependency correction
Hand off for follow-up analysis

Recommend the next tasks, with rationale and urgency
If edits to canonical planning documents are recommended, request explicit confirmation before generating file-level change proposals

Phase 4: Persistence report

Write the report to:

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

In addition to the human-readable section, the report must contain a machine-readable drift block (YAML or JSON). The report must also include an evidence readiness block and an explicit confidence level.

Input & Output

Input

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

Output

Planning adjustment 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"

Limits

Hard Boundaries

When evidence is missing, do not invent traceability links
When the readiness status is "weak" or "missing", do not claim high confidence
Do not silently modify the planning source of truth (goals, requirements, milestones, roadmap) without explicit user approval
Do not collapse drift categories into a generic "misalignment" bucket; preserve the input drift outputs (goals, requirements, roadmap, priorities)
Do not skip layer checks in full mode unless that layer is truly unavailable (mark as "unknown" and explain)
Do not make recommendations without a rationale tied to traceable evidence

Skill Boundaries (avoid overlap)

Do not do these (other skills can handle them)：

Requirements redefinition workflow →分析需求
Architecture option design workflow →设计解决方案
Repository-level onboarding → review-codebase、generate-standard-readme、generate-agent-entry (run in order as needed)
Automated test and fix loop execution → run-repair-loop

When to stop and hand off：

Requirements invalid or contradictory → hand off to "analyze requirements"
Architecture design conflict is the main obstacle → hand off to "design solution"
Need to perform architecture and code compliance check → hand off to "align-architecture"
Report indicates proactive implementation defects requiring fixes → recommend "run fix loop"

Self-Check

Core success criteria (all must be met)

Backtracking for the selected mode is complete
Drift items typed using the four planning models
Each drift has impact scope and root cause
Provide top-down calibration actions
The report adheres to the agreed path
Clearly report evidence readiness level and confidence
Request confirmation when mapping or write safety is uncertain

Process quality checks

Mode selection follows a deterministic policy
Mapping uncertainty triggered "NeedsMappingConfirmation"
Normative evidence is clearly separated from secondary evidence
Each alignment status has an evidence reference
Recommendations are prioritized and time-bound
Can explicitly hand off to adjacent skills when needed

Acceptance test

Can a team member execute the top 1-3 recommendations without additional explanation and explain why they have the highest priority?

If no: the report is incomplete; refine traceable evidence and recalibration details.

If yes: the report is complete; proceed to handoff or execution plan.

Example (Example)

Example 1: Lightweight mode (routine task)

Context: completed task updated the search filter UI behavior.

Mode resolution: no explicit override, no release/milestone/epic markers → lightweight.

Backtracking：

The task is consistent with the roadmap item "search-improvements-q2"
The requirement is still valid, but the acceptance criteria changed last week
Evidence readiness "strong", because both the requirements and roadmap documents are normative and up to date

Drift：

-"Requirements drift" (medium): the requirement wording was changed to include keyboard navigation; the completed task only covers click interaction

Calibration：

1. Add follow-up tasks for keyboard navigation 2. Move accessibility acceptance checks before merging related UI tasks 3. Reorder to-do items to unlock regression tests

Example 2: Full mode (milestone closed)

Context: A milestone marked as "milestone closed" after the API gateway authentication rollout.

Mode resolution: marker hit → full.