155 lines
6.6 KiB
Markdown
155 lines
6.6 KiB
Markdown
---
|
|
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:
|
|
|
|
```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
|
|
|
|
Unusual situations — an empty target, a partial run, a conflicting state,
|
|
a missing dependency — are catalogued in
|
|
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
|
|
run hits something the steps above don't cover; don't load it otherwise.
|