ckb/.agents/skills/ckb-project-summary/SKILL.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

6.6 KiB


name: ckb-project-summary description: Generate or refresh a one-to-two-page project overview at the repo root, synthesized from current wiki/ contents: overview, project state, actions and their status, risks, and assumptions. Use for "project summary", "project overview", "where do things stand", or "summarize the project".

Project summary skill

Purpose

Everything in the overview must trace back to what the wiki says; it adds no claims or guesses. wiki/ stays authoritative: re-running regenerates the file from the wiki as it is now rather than appending to the last one.

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_<author>_summary.md (by filename date, whichever author) 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

Unusual situations — an empty target, a partial run, a conflicting state, a missing dependency — are catalogued in references/edge-cases.md. Read that file when a run hits something the steps above don't cover; don't load it otherwise.