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

name

description

ckb-project-summary

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:

# [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.

---

Licensed under the Apache License, Version 2.0 — see LICENSE at the repository root, or http://www.apache.org/licenses/LICENSE-2.0.