Generate Plan Fact Report

generate-plan-fact-report

Language Detection

Determine the language of the user's request:

• If the request is in Russian → use templates with -ru suffix
• Otherwise → use templates with -en suffix

All output (headings, labels, comments, instructions) must match the detected language.

Triggers

Russian: «сформируй план-факт», «подготовь отчёт план/факт», «сравни план и факт» English: "generate plan-fact report", "plan vs actual", "variance report"

1. Input Data

| Data | Required | Source | Notes | |------|:--------:|--------|-------| | Project plan | yes | knowledge (project-plan.md) | Milestones, timelines, budget. If budget is missing — Section 3 is not generated | | Actual data | yes | chat | User provides: actual milestone completion dates, actual costs by budget line, deliverable status. Free-form — agent structures it | | Project charter | no | knowledge (project-charter.md) | For deliverables list (Section 1, scope). If unavailable — request the list from the user | | Report type | no | chat | interim (default) or final. Affects header label only — logic is identical |

If required data is missing — request it:

To generate the plan-vs-actual report, the following are needed:
1. Project plan (project-plan.md) — in knowledge or paste into chat.
2. Actual data — in any format:
   — milestone completion dates (completed, not completed, actual date);
   — actual costs by budget line;
   — which deliverables have been delivered and which have not.
Available: [list what is present].
Missing: [specify].

---

2. Execution Algorithm

1. Check input data. Verify project plan and actual data are present. Missing → request using the template in §1. Do NOT generate a placeholder report. Present → proceed to step 2.
2. Structure actual data. If free-form — organize across three dimensions: timelines (milestone dates), budget (costs by line), scope (deliverables). Note ambiguities and clarify with the user.
3. Check for data conflicts. If plan data in chat conflicts with project-plan.md — do NOT resolve independently. List the conflicts and ask which data is current. Exception: if the user explicitly corrects the plan in chat — apply the correction.
4. Determine report period. From actual data: project start → date of last recorded fact. If the user specified a period explicitly — use it.
5. Read the template plan-fact-report-ru.md or plan-fact-report-en.md from project knowledge (based on detected language).
6. Extract planned data from project-plan.md: milestones with dates, budget lines with amounts, deliverables list.
7. Compare plan vs. actual. For each row: calculate variance (absolute and %), assign status per §3 reference table.
8. Fill template sections per Section 3 rules.
9. Evaluate whether Section 4 is needed. Check statuses for all three dimensions independently: Timelines, Budget, Scope. Scope is a full dimension equal to timelines and budget. If at least one of the three has status attention or critical (including scope with incomplete deliverables) → fill Section 4. Only if all three are on track → remove Section 4 entirely.
10. Validate the result using the checklist in Section 5.
11. Present the result in chat:

• What was done: "Plan-vs-actual report generated for period [dates] based on [list sources]."
• Assumptions: list all (if any).
• Key variances: brief (1–3 lines) — main discrepancies and their statuses.
• Required action: "Approve, revise, or reject."
• Do not include internal file paths. Filename only: "Report saved as plan-fact-report.md."

1. Wait for user response.

• Approval → finalize the document.
• Revisions → revise and present updated version. After the 3rd iteration — ask: "Continue revising or lock current version?"

1. After approval:

• Offer the user text for log.md and project-state.md.
• Always notify, regardless of report type and variance statuses: "Plan-vs-actual report approved. Next task available: generate-closure-report (project closure report). Start?"

---

3. Section Fill Rules

Reference: Variance Status Calculation

Applied to each parameter in Section 1 (summary) and to rows in Sections 2–3.

| Variance, % (absolute value) | Status | |------------------------------|--------| | ≤ 10% | on track | | 11–25% | attention | | > 25% | critical |

Sign convention: positive = overrun / delay / shortfall; negative = savings / ahead of schedule / surplus.

Section 1. Summary

Three rows — aggregated variances across three dimensions.

• Timelines: Plan — total project duration (working days or calendar days). Actual — actual duration as of report date. If project is not complete — show actual duration with note "project not complete."
• Budget: Plan — total from project-plan.md (or project-charter.md). Actual — sum of actual costs. Currency from input data.
• Scope: Unit — number of deliverables from project charter (project-charter.md, Section 2 "Project Deliverables"). Plan — total count. Actual — delivered count. If charter unavailable — request the deliverables list from the user.

For each row: calculate absolute variance, variance %, status per reference table.

Summary commentary — required text block after the table. 1–2 sentences per dimension: nature of variance and its cause. If status is on track — state the fact without detailed analysis.

Section 2. Timelines

Row-by-row comparison of milestones from project-plan.md.

• Include all milestones from the plan — not only completed ones.
• If a milestone is not complete — enter not complete in "Actual Date." Variance — dash.
• Variance in days: actual_date - planned_date. Positive = delay, negative = ahead of schedule.
• "Variance reason" — fill from user-provided actual data. If reason not stated — enter [clarify].

Section 3. Budget

Row-by-row comparison of cost lines from project-plan.md (or project-charter.md).

• Include all cost lines from the plan. If no actual data for a line — actual = 0, note "data not provided" in comment.
• Last row — Total: sum of all rows. Verify: total actual = sum of actual rows.
• If a cash flow plan (breakdown by period) is unavailable — use linear distribution of budget over project duration, note estimated in comment. State as assumption.
• Currency — uniform across the entire report, from input data.

If budget is missing from the project plan and charter — Section 3 is not generated. Replace with note: "Budget section not included: planned budget data unavailable." In the summary (Section 1), replace the budget row with: "Budget — data unavailable."

Section 4. Recommendations / Next Steps

Conditional section. Generate only if at least one of the three dimensions (Timelines, Budget, Scope) has status attention or critical. Scope is an independent dimension — its critical/attention status triggers Section 4 independently, even if timelines and budget are on track. If all three are on track — remove Section 4 entirely.

• For each variance with status attention or critical — formulate a recommended action.
• Specify the owner (from project data) and deadline (if determinable from context). If not — [clarify].
• Minimum 1 recommendation per critical variance.

Header Metadata

• Version: 1.0
• Date: current generation date
• File: plan-fact-report.md
• Document status: draft (at generation). After approval — approved.
• Period: {{start_date}} — {{end_date}}
• Report type: interim or final (from input; default interim)
• Planned data source: filename (e.g. project-plan.md)
• Actual data source: source description (e.g. "PM data provided in chat")

---

4. Placeholder Reference

> Placeholders {{}} in the template are fill targets, not auto-substitution variables. Replace each with the corresponding value from input data.

| Placeholder | Required | Source | Allowed Values | |-------------|:--------:|--------|----------------| | {{project_name}} | yes | plan / charter | text | | {{date}} | yes | system | YYYY-MM-DD | | {{start_date}} | yes | plan / chat | YYYY-MM-DD | | {{end_date}} | yes | chat | YYYY-MM-DD | | {{report_type}} | yes | chat (default: interim) | interim / final | | {{source_plan}} | yes | context | filename of planned data source | | {{source_fact}} | yes | context | description of actual data source | | {{planned_duration}} | yes | plan | number + unit (days / working days) | | {{actual_duration}} | yes | actual | number + unit | | {{delta_time}} | yes | calculated | signed number | | {{delta_time_pct}} | yes | calculated | signed % | | {{status_time}} | yes | calculated | on track / attention / critical | | {{currency}} | yes | plan / chat | currency symbol (₽, $, €) | | {{planned_budget}} | no | plan | number | | {{actual_budget}} | no | actual | number | | {{delta_budget}} | no | calculated | signed number | | {{delta_budget_pct}} | no | calculated | signed % | | {{status_budget}} | no | calculated | on track / attention / critical | | {{planned_scope}} | yes | charter / plan | number (deliverable count) | | {{delivered_scope}} | yes | actual | number (delivered count) | | {{delta_scope}} | yes | calculated | signed number | | {{delta_scope_pct}} | yes | calculated | signed % | | {{status_scope}} | yes | calculated | on track / attention / critical | | {{milestone_name}} | yes (≥1) | plan | milestone name | | {{planned_date}} | yes | plan | YYYY-MM-DD | | {{actual_date}} | no | actual | YYYY-MM-DD or not complete | | {{delta_days}} | no | calculated | signed day count or dash | | {{reason}} | no | actual / agent | text or [clarify] | | {{cost_item}} | no | plan | cost line name | | {{planned_cost}} | no | plan | number | | {{actual_cost}} | no | actual | number | | {{delta}} | no | calculated | signed number | | {{delta_pct}} | no | calculated | signed % | | {{comment}} | no | actual / agent | text | | {{total_plan}} | no | calculated | sum of planned rows | | {{total_fact}} | no | calculated | sum of actual rows | | {{total_delta}} | no | calculated | difference of totals | | {{total_delta_pct}} | no | calculated | % variance of total | | {{issue_N}} | no | agent | issue / observation description | | {{action_N}} | no | agent | recommended action | | {{owner_N}} | no | project data | owner or [clarify] | | {{deadline_N}} | no | agent | deadline or [clarify] |

---

5. Validation Checklist

Before presenting the result to the user — verify:

• [ ] All required placeholders replaced with values
• [ ] No {{}} placeholders remaining in the text (except removed optional rows)
• [ ] Report period is valid: start_date 25%)
• [ ] Section 2: all milestones from the plan included (not only completed)
• [ ] Section 2: incomplete milestones show "not complete," variance is a dash
• [ ] Section 3: total = sum of rows (verify arithmetic)
• [ ] Section 3: if budget missing — section replaced with note
• [ ] Section 4: present if any attention/critical variances; absent if all on track
• [ ] All agent assumptions listed when presenting the result
• [ ] Document status = draft
• [ ] File: plan-fact-report.md stated in header

---

6. Dependencies

Consumes (input):

• project-plan.md — from skill generate-project-plan (milestones, budget, timelines)
• project-charter.md — from skill generate-charter (deliverables for scope metric)
• Actual data — from the user (via chat)

Produces (output): plan-vs-actual report → consumed by:

• generate-closure-report — Phase 6, Closing

After approval, the user must upload plan-fact-report.md to project knowledge so it is available for generate-closure-report.

---

7. Usage Example

User command:

> Generate a plan-vs-actual report. Project plan is in knowledge. Actual data: > — M1 (Go/No-Go): completed 11.04, on time. > — M2 (Plan approved): completed 25.04, on time. > — M3 (Prototype): completed 12.05, 3-day delay — design approval. > — M4 (Development): not complete. > — Budget: AWS — $10,400 (planned $8,000), design — $10,000 (on plan), rest on plan. > — Deliverables: 3 of 5 delivered.

Agent response (after generation):

> Plan-vs-actual report generated for period 07.04.2026 — 12.05.2026 based on: project-plan.md (knowledge), actual data from chat. > > Assumptions: > - Budget lines without explicit data: actual = planned. > - Duration: actual — 35 days (from start to report date), planned — 63 days (full project). Project not complete. > > Key variances: > - Scope: 3/5 deliverables (−40%) — status critical. > - AWS budget: +$2,400 (+30%) — status critical. > > Required: approve, revise, or reject. > > [report text]

---

Changelog

| Date | Version | Change | |------|---------|--------| | 2026-03-27 | 1.1 | §2 step 9: scope is an independent trigger for Section 4 (all three dimensions listed explicitly); §2 step 13: generate-closure-report offer is mandatory regardless of statuses; §3 Section 4: clarified that scope independently activates the section | | 2026-03-26 | 1.0 | Skill created. Output format .md. Status calculation rules, conditional Section 4, scope metric — deliverables |

Source & license

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

• Author: KirKruglov
• Source: KirKruglov/claude-skills-kit
• License: MIT

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