ckb/.agents/skills/project-summary/SKILL.md

---
name: project-summary
description: Generate or refresh a one-to-two-page project overview at the repo root, synthesized entirely from the current wiki/ contents — overview paragraph, project state, actions and their status, risks, and assumptions. Use when the user asks for "a project summary", "project overview", "give me the state of the project", "where do things stand", "summarize the project", or wants a quick top-level snapshot without reading the whole wiki.
---

# Project summary skill

## Purpose

Produce a short, standalone snapshot of the project at repo root - something
a busy stakeholder can read in two minutes without opening `wiki/` at all.
Everything in it must trace back to what the wiki actually says; this is a
synthesis of existing knowledge, not a place to add new claims or guesses.

This is a one-way, on-demand export - `wiki/` stays the authoritative
source; the generated overview file is always a derived, refreshable
snapshot. Re-running the skill regenerates it from whatever the wiki says
*now*; it does not append to the previous version.

## Trigger phrases

Use this skill when the user says things like:
- "give me a project summary" / "project overview"
- "where do things stand" / "what's the state of the project"
- "summarize the project" / "one-pager" / "two-pager"
- "catch me up on the project"

## How to run this skill

### Step 1 - Identify the project

Read `wiki/index.md` and `wiki/entities/index.md` first (small, cheap,
gives the lay of the land). Then find every entity page whose frontmatter
has `type: project`.

- **Exactly one** - that's the subject, proceed.
- **None found** - tell the user no `type: project` entity exists yet in
  the wiki, and ask whether to point at a specific entity page instead or
  run Ingest first. Do not fabricate a project summary from thin air.
- **More than one** - list them (title + `tldr`) and ask which one to
  summarize, or whether they want a separate overview file for each.

### Step 2 - Gather context via the graph, not just one page

Read the chosen project entity page in full. Then read
`wiki/graph/edges.json` and pull every edge where this entity is the
`source` or `target` - these are its direct dependencies. Read each of
those pages in full too. If a dependency page itself has further edges
that look load-bearing (e.g. another concept it depends on), follow one
more hop - but stop there. This is a snapshot, not a full graph traversal;
two hops is enough to be accurate without pulling in the entire wiki.

Also check the single most recent `workload/YYYY-MM-DD_summary.md` (by
filename date) for anything very recent that may not have made it into the
wiki yet. Treat the wiki as authoritative if the two conflict - workload
files are a running log, not a maintained source of truth - but note a
real discrepancy in Project State rather than silently picking one.

### Step 3 - Extract and classify

Work through everything gathered in Step 2 and sort content into five
buckets. Do not pad any section to look complete - a short, honest section
is better than filler, and it's fine for Risks or Assumptions to be thin or
even say "none currently recorded" if that's genuinely the case.

1. **Overview** - one short paragraph: what the project is, who's involved
   (client / delivery org / key roles), and what it's for. This is
   scene-setting, not a list of facts.

2. **Project State** - the current concrete status: what phase things are
   in, what's confirmed vs. pending, key dates. Pull directly from
   "Current Shape" / "Management Summary" / status-like sections on the
   entity pages gathered.

3. **Actions & Status** - every concrete to-do, next step, or open item
   found across the gathered pages (commonly under headings like "Open
   Points" or "Open items"). Dedupe overlapping items from different pages
   into one line. Assign a status to each from this fixed vocabulary based
   on the page's own wording - don't invent a finer-grained scheme:
   - **Done** - completed, confirmed, signed, resolved
   - **In progress** - actively being worked, partially complete
   - **Blocked** - explicitly waiting on something else before it can move
   - **Open** - identified but not yet started or scheduled

4. **Risks** - things that could hurt the project if they go wrong or stay
   unresolved. Look for language like "risk", "concern", "gap", "blocked
   on", "unresolved", "dependent on", "may not stick", "left dependent on."
   For each: what the risk is, why it matters, and - if the source says so
   - what would mitigate or resolve it.

5. **Assumptions** - things the current plan depends on being true but that
   aren't yet confirmed. Look for language like "expected", "should",
   "likely", "assuming", "TBC", "to be confirmed", "time-bound", "reconfirm
   before acting." For each: what's assumed, and what would need to happen
   to confirm or invalidate it.

An item can legitimately touch both Risks and Assumptions (an unconfirmed
assumption is often also a risk if it turns out false) - when that
happens, put it wherever it fits better and don't duplicate it in both.

If there's more candidate material than fits a one-to-two-pager, prioritize
by what the source pages themselves flag as higher-confidence, higher-
retention, and most recently updated - this is a snapshot of what matters
most right now, not an exhaustive appendix.

### Step 4 - Write the file

Target length: one to two pages (roughly 500-900 words total, including
bullets - err short over long). Write to `PROJECT-OVERVIEW.md` at the repo
root, overwriting it completely if it already exists (this is a refreshable
snapshot, never hand-append to a previous version).

Use this structure:

```markdown
# [Project Name] - Project Overview

*Auto-generated from `wiki/` - do not hand-edit; regenerating this skill overwrites this file. Last generated: YYYY-MM-DD.*

**At a glance:** [client] · [delivery org] · [one-line phase/status]

## Overview

[the synthesis paragraph]

## Project State

[status bullets or short paragraph]

## Actions & Status

| Action | Status |
|---|---|
| ... | Done / In progress / Blocked / Open |

## Risks

- **[risk]** - [why it matters] [mitigation if known]

## Assumptions

- **[assumption]** - [what would confirm/invalidate it]

---
*Sources: [wiki pages used, as markdown links]*
```

Use plain markdown links to the wiki pages actually used (e.g.
`[Grant Thornton FDE engagement](wiki/entities/grant-thornton-fde-engagement.md)`)
so a reader can jump to the full detail behind any line. Keep the source
list to what was actually used, not every page in the wiki.

If more than one `type: project` entity was chosen for separate summaries
(Step 1), name the files `PROJECT-OVERVIEW-<slug>.md` instead of the plain
name, using a short kebab-case slug of the project's title.

### Step 5 - Report

Tell the user the file was written (path), give a one-line gist of what it
found (e.g. "3 open actions, 2 risks, 1 assumption"), and mention it can be
regenerated any time by re-running this skill - it will always reflect
whatever the wiki says at that moment, not what it said today.

## Edge cases

- **Empty or near-empty project entity page** - write a short, honest
  Overview and State, and let Actions/Risks/Assumptions be genuinely short
  rather than inventing content to fill the template.
- **Conflicting information between two source pages** - prefer the page
  with the more recent `last_updated`; if they're the same date, note the
  conflict briefly in Project State rather than silently picking one.
- **`PROJECT-OVERVIEW.md` already exists** - overwrite it; this file is
  always meant to reflect the current wiki, not accumulate history. If the
  user wants history, that's what `wiki/log.md` and `workload/` are for.
- **Re-running with no wiki changes since the last run** - should produce
  essentially the same content each time; don't introduce random variation
  in section content or ordering between runs.