- Skills: descriptions cut to routing-hint length (1925w -> 840w), Trigger
phrases removed, Purpose collapsed, Edge cases moved to references/.
- Rule B names the decisions-log exception; "Sync the wiki" trigger dropped;
reserved sections "Four" -> "Three"; directory contract adds ckb.yaml,
docs/, tests/.
- MANUAL/CHANGELOG/OPENSPEC (EN+PL) moved to docs/; template ADRs D-0001 and
D-0002 restored from 0c06cb6 into docs/decisions/; referrers repointed.
- ckb-retrieve: rank fusion moved into scripts/retrieve_candidates.py;
Purpose states the one write it owns (query-gaps).
- tests/: fixture KB, golden JSON, smoke.sh.
- Scaffold: overview.md describes content not schema; graph/index.md names
base skills only; query-gaps.md loses its self-rotting freshness window.
- README/MANUAL/OPENSPEC/CHANGELOG ghost-writer pass in both languages.
- VERSION 1.9.0 -> 1.10.0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
6.8 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
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.
One-way and on-demand: wiki/ stays authoritative and the generated overview is a
derived, refreshable snapshot. Re-running regenerates it from whatever the wiki says
now; it does not append to the previous version.
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: projectentity 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.
-
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.
-
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.
-
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
-
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.
-
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.