| name | lythoskill-project-scribe-weekly |
| version | 0.17.2 |
| description | Weekly synthesis writer. Distills the past 7 days' core thread + quest DAG
into a frontmatter-rich short doc. Never replays git log or cortex INDEX
(those are direct queries already). Forms the weekly counterpart to
project-scribe (daily) and project-onboarding (read-side).
|
| when_to_use | End of week retrospective, planning next week's priorities, zooming out
from daily noise, identifying patterns across sessions, preparing for
epic planning, Sunday night wrap-up, 周末复盘.
|
Project Scribe — Weekly
Distill, don't replay. The core thread matters; the 17 commits that touched it don't.
Value Boundary
Weekly is a memory offloading mechanism, not a menu listing.
| Direct queries (skip these) | Scribe-weekly must synthesize |
|---|
git log --since="7 days ago" | The one decision that mattered most |
ls daily/2026-05-* | Why the planned vs actual divergence happened |
cat cortex/INDEX.md | Which emergent threads earned attention |
bunx @lythos/project-cortex list | What pattern is hardening into a project trait |
If the next agent can find it via ls daily/, git log, or cortex index — don't replicate it. Link to it.
Why this matters: A future agent reading a weekly cold (no daily access) should get the compressed representation of the week's cognitive work — the pattern, not the commits. Without this, every agent must reconstruct the narrative from 6 daily files + 29 commits + 10 ADRs. Weekly offloads that reconstruction cost once, permanently.
Weekly Prep (like cortex probe — gather before you write)
Do NOT start writing from memory. Run prep first. This is the write-side counterpart to onboarding's read-side: just as onboarding reads daily → verifies git → presents summary, weekly prep gathers all sources → surfaces anomalies → ranks importance.
Step 1: Gather (deterministic)
python3 -c "import datetime; d = datetime.date.today(); iso = d.isocalendar(); \
mon = d - datetime.timedelta(days=d.weekday()); \
sun = mon + datetime.timedelta(days=6); \
print(f'Today: {d} ({d.strftime(\"%A\")}) — ISO W{iso.week}'); \
print(f'Standard span: {mon}_to_{sun}')"
ls daily/*.md | sort | tail -7
git log --since="7 days ago" --oneline
bunx @lythos/project-cortex@0.17.2 probe
bunx @lythos/project-cortex@0.17.2 stats
ls -lt cortex/adr/02-accepted/ | head -15
ls weekly/ | sort | tail -1
Step 2: Surface Anomalies
Scan the gathered data for:
- Superseded decisions: later ADR that contradicts an earlier one (e.g., combo redefinition May 6 superseded May 1 section semantics)
- Renamed/removed commands: CLI surface changed (e.g.,
agent-run → single, deck sync → deck to-symlink)
- Reversed priorities: a task/epic that was
priority_at_start last week but never appeared in this week's dailies
- Silent gaps: days with no daily file but git shows commits (someone committed outside agent session)
- Missing ADRs: significant code/architecture change in git log with no corresponding ADR accepted in the same window. A rename with 30+ commits and no ADR is a red flag.
Step 3: Importance Ranking (simulated annealing)
- High temperature: dump every event you can recall. Don't filter. Include everything.
- Cool: group related events into clusters (e.g., "path convention fixes" = 5 commits, 2 ADRs, 1 ZK sweep)
- Rank clusters by downstream confusion cost: "if a future agent missed this cluster, how wrong would their decisions be?"
- Freeze: top 1-2 clusters →
core_thread. Clusters that involve superseded docs → docs_now_stale.
Test: can you identify the single most important decision of the week? If the combo redefinition (May 6) would be invisible in your weekly, you didn't rank correctly.
Step 4: Prep Report (show to user before writing)
Present a 5-line summary:
📊 Weekly Prep — 2026-W22
📄 Dailies: 2026-05-21, 2026-05-28 (gap May 22-27)
🔀 ADRs: 3 proposed, 0 accepted this period
⚠️ Anomalies: combo redefinition (May 6) not captured in any weekly
💡 Top cluster: site documentation debt cleanup (P0 → done)
📋 docs_now_stale candidates: ADR-20260501160000000, external-skill-governance-bridge.md
User confirms → proceed to write. User flags missing items → add to cluster list.
When to Run
- User explicitly asks for weekly synthesis
- End of week (typically Sunday) for retrospective
- Friday afternoon: if the week has already produced substantial work and user wants to capture it before weekend
- Sunday night: if weekend work continued the week's thread — append to existing weekly, don't create new
- Monday: if weekend was quiet and weekly wasn't written yet
- Before epic planning to understand what unlocked/paused
- Do NOT auto-schedule — the player decides timing
Sunday Check (agent-initiated suggestion)
If today is Sunday and you observe any of these signals during session close:
- Epic/task cleanup feeling ("this phase feels done")
- Goal 阶段性达到 (milestone completed, tests pass, push to remote)
- User says "LGTM", "就这样", "先到这里" on a Sunday
Suggest to user: "今天周日，这周的工作感觉到了一个自然的收束点。要不要沉淀一下 weekly，把这周的模式记录下来？"
User says yes → run weekly prep. User says no or ignores → write daily scribe as usual, don't push.
Weekly Writing Modes
| Mode | When | Action |
|---|
| Fresh | No weekly exists for current week | Write new weekly with standard period |
| Append | Weekly already exists, weekend had more work | Append to existing weekly, update core_thread if needed |
| Catch-up | Gap week(s) detected | Write "no active work" weekly for gap, then current week |
Daily scribe continues regardless. Weekly does not replace daily; they are different abstraction layers.
Inputs (collect before writing)
ls daily/*.md | sort | tail -7
git log --since="7 days ago" --oneline
bunx @lythos/project-cortex@0.17.2 index
bunx @lythos/project-cortex@0.17.2 stats
Output: weekly/YYYY-Wxx.md
Frontmatter (machine-readable; future agents read this first)
---
period: 2026-05-01_to_2026-05-07
core_thread: "one-line synthesis of the week's unifying theme"
priority_at_start:
- "what was planned"
priority_at_end:
- "what actually became priority"
quests_advanced:
- EPIC-xxx: epic name (status)
quests_unlocked:
- "new task or epic that became actionable"
quests_paused:
- "task or epic that was deferred"
parked_threads:
- "noted but not pursued"
decisions_accepted:
- ADR-xxx: decision title
retro_cells:
planned_done: "what was planned and completed"
planned_paused: "what was planned but didn't happen (and why)"
emergent_done: "what emerged and earned attention"
emergent_paused: "what emerged but was parked"
project_lesson_candidates:
- "pattern that might become a wiki entry if it repeats"
references:
daily: ["daily/2026-05-01.md", "daily/2026-05-02.md", ...]
cortex_index: cortex/INDEX.md
---
Body (~200-300 words, NOT a replay)
- TL;DR (1 paragraph): core thread + the one decision that mattered most.
- 4-Quadrant Retro (table): planned vs emergent × done vs paused.
- Quest DAG: ASCII or Mermaid diagram of epic/task flow.
- Project Lesson Candidates: bullets for patterns worth crystallizing.
- Reference Pointers: links to daily files and indexes. Don't replicate.
The 4-Quadrant Retrospective
Compare intended priorities against actual execution:
| Done | Paused / Dropped |
|---|
| Planned (priority at start) | ✅ Validated priorities — called right | ⚠️ Priority correction — why did it slip? |
| Emergent (surfaced mid-week) | 🌱 What proved deserving of attention | 📋 Noted-but-parked threads |
Rule of thumb: One concise line per cell explaining what happened and why. Not a task list.
Salience Filter
"太细节的小事不会在 weekly 里。特别强烈的印象会在。"
| Include | Exclude |
|---|
| Decisions that changed direction | Every commit message |
| Patterns across multiple days | Single-day bugs already fixed |
| Unblocked epics or tasks | Routine maintenance |
| Surprising findings from E2E | Formatting changes, refactors |
| Project traits worth documenting | Tool version bumps |
Test: If a future agent reading this weekly cold (no daily access) would mistake a detail for a non-event, it doesn't belong.
Verify Companion
Before relying on a weekly for planning, spot-check its claims against ground truth:
bunx @lythos/project-cortex@0.17.2 probe
git log --since="2026-05-01" --until="2026-05-07" --oneline
ls daily/2026-05-*.md
Wrong facts in weekly = disaster for next agent. The agent owns this verification — there is no validate-weekly CLI; weekly is a pure skill that produces a doc, the agent uses cortex probe + git log + daily ls to reality-check what it just wrote.
Decision Hygiene (agent behavior)
Do not present fake options. When asking user for next step, every option must be a real choice with different consequences. Do not include:
- Options that transfer cost to future sessions (e.g., "end session and let next agent handle it")
- Options that are obviously inferior (e.g., "do nothing" when action is clearly needed)
- Options that defer without reason (e.g., "wait" without explaining what we're waiting for)
Why: Fake options waste user attention. They feel like marketing tricks — psychological anchors designed to make one option look good by contrast. Respect user time by offering genuine trade-offs or making the recommendation directly.
Pattern: If you know what should happen, say so. If you need user input, offer 2-3 real alternatives with consequence briefs. If there's no real choice, don't ask.
Examples:
- ❌ "Should I A) verify now B) end session C) do nothing" — C is fake
- ✅ "I recommend verifying now — cost is 1 minute, benefit is catching skill drift before next session. Confirm?"
- ✅ "Two paths: A) quick scan (5 min, surface only) B) deep audit (30 min, full checklist). Which fits your time?"
Scenarios & Packages (v0.1 — explore with user)
Weekly writing is not a rigid procedure. It's a scenario-driven, package-based exploration between agent and user. Like an ADV game: there are branches, but each branch has a default skeleton.
Scene A: Weekly Writing
Trigger: User says "写 weekly" / "这周总结一下" / end-of-week feeling
| Package | When | Skeleton | Optional Add-ons |
|---|
| A1: Fresh | No weekly for current ISO week | Standard ISO period + full prep | ADR timeline, daily cross-reference |
| A2: Append | Weekly exists, work continued | Extend period, update core_thread | Merge cross-week git activity |
| A3: Catch-up | Gap detected | Fill gap with "no active work" first, then write current | Historical drift annotation |
Agent choice: Run ls weekly/*.md | sort | tail -3 to detect mode. Recommend package to user. User confirms or overrides.
Scene B: User Says "消债" / "扫一下" / "还债"
Trigger: User explicitly asks for cleanup / audit / sweep
| Package | When | Skeleton | Optional Add-ons |
|---|
| B1: Quick Scan (5 min) | User wants overview | Weekly chain + cortex probe | Gap report only |
| B2: Deep Audit (30 min) | User wants thorough check | Full 23-item reference checklist | User selects scope |
| B3: Targeted | User names specific debt | Agent drills from weekly chain into named area | Cross-reference ADR/task |
Agent choice: Ask user "quick scan or deep?" Default to B1 if user just says "消债" without qualifier.
Scene C: Session Close (Scribe)
Trigger: User says "LGTM" / "先到这里" / session ending
| Package | When | Skeleton | Optional Add-ons |
|---|
| C1: Standard Handoff (default) | No weekly suspicion | Write daily, no eager weekly check | — |
| C2: Weekly Suspicion | User mentions cross-week work / weekly conflict | Check weekly chain before scribe | Suggest append if needed |
Agent choice: Default C1. Switch to C2 only if session content clearly spans weeks or user explicitly mentions weekly.
Scene D: Release Prep
Trigger: User says "release" / "ship it" / version bump
| Package | When | Skeleton | Optional Add-ons |
|---|
| D1: Version Alignment | Pre-bump | Check package.json versions across packages | README version sync |
| D2: Reference Validity | Pre-publish | Check internal links, cross-package refs | External link spot-check |
| D3: Full Sweep | Major release | All 23 items + documentation freshness | Dreaming integration |
Agent choice: User names release scope → select package. Default D1 for patch, D2 for minor, D3 for major.
Scene E: Quarterly Dreaming
Trigger: User says "做梦" / "consolidate" / "memory cleanup"
| Package | When | Skeleton | Optional Add-ons |
|---|
| E1: Trend Analysis | Every quarter | Weekly chain pattern + lesson candidate validation | Wiki promotion decisions |
| E2: Full Archive | Year-end / major milestone | All 23 items + historical drift full audit | SSOT regeneration |
Agent choice: Dreaming skill owns this. Weekly skill provides weekly chain as input.
23-Item Reference Checklist (menu, not mandate)
Use this as a menu when user selects B2 (Deep Audit) or D3 (Full Sweep). Not for everyday use.
1. Document Chain Integrity
2. Code-Document Consistency
3. Governance State Consistency
4. Reference Validity
5. Metadata Completeness
How to use: Agent presents checklist to user. User selects scope ("just 1 and 3" or "all"). Agent executes selected items. No automatic full scan.
Long-Range Consistency Principle
Weekly is the anchor for long-range consistency. Not because it's the most frequent, but because it's the right frequency:
- daily: too frequent, compaction makes it unreliable for drift detection
- weekly: just right — regular enough to catch drift, sparse enough to survive compaction
- quarterly: too sparse, drift accumulates beyond easy repair
The weekly chain (weekly/2026-W17.md, 2026-W18.md, ...) is a temporal index. Future agents reading cold can:
- Find the latest weekly → know current ISO week
- Follow chain backward → reconstruct narrative
- Detect gaps → know where drift occurred
This is the project's memory infrastructure in practice.
