1f7a85b7d1
Skill that triggers at the end of every coding session where files changed. Enforces structured session notes with label, narrative, and four fields (What, Why, How, Touches) at one-entry-per-logical-change granularity. Includes reference examples from the Loom project and review-ready CLAUDE.md with key patterns documented.
61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
# Example Session Entry
|
|
|
|
This is a reference example showing the right granularity and writing
|
|
style for session notes. Each change is its own entry with specific
|
|
detail about what, why, how, and what files were touched.
|
|
|
|
---
|
|
|
|
## Session — 2026-04-27
|
|
|
|
### Trello REST Client
|
|
Wraps the Trello board API with httpx. Fetches lists and cards, groups
|
|
cards by label name (which is the project slug). Includes in-memory cache
|
|
with configurable TTL so the dashboard doesn't hit Trello on every page
|
|
load.
|
|
|
|
- **What:** `TrelloClient` class with card grouping and TTL cache
|
|
- **Why:** Dashboard needs live Trello card state joined to vault data
|
|
- **How:** httpx.Client with 15s timeout. `_fetch_all()` populates cache
|
|
dict with lists and cards. `get_cards_by_project()` groups cards by
|
|
label name. `get_list_for_project()` returns highest-priority list
|
|
name using a priority map (Active=0, On Deck=1, etc). `refresh()`
|
|
invalidates cache.
|
|
- **Touches:** data/trello.py (new)
|
|
|
|
### Loose Thread Scanner
|
|
Scans all vault .md files for unchecked `- [ ]` checkbox items. Returns
|
|
them as LooseThread objects with the text, project slug, and source file.
|
|
Found 862 items across the real vault.
|
|
|
|
- **What:** `find_loose_threads()` returns list of LooseThread
|
|
- **Why:** "What loose threads have I left" — unfiled commitments
|
|
- **How:** Regex `^(\s*)-\s+\[\s\]\s+(.+)$` with MULTILINE flag. Scans
|
|
all .md files regardless of type. Uses project slug from frontmatter
|
|
if available, falls back to filename stem.
|
|
- **Touches:** data/sessions.py
|
|
|
|
### Path Traversal Fix
|
|
Gemini CLI review caught that _log_session accepted arbitrary slugs that
|
|
could write outside the vault directory via `../../` paths. Added slug
|
|
validation regex and resolved-path containment check.
|
|
|
|
- **What:** Slug validation + path containment for MCP write tools
|
|
- **Why:** Security — prevent path traversal via malicious slug input
|
|
- **How:** _SLUG_RE regex `^[a-z][a-z0-9-]*$` rejects anything with dots,
|
|
slashes, or uppercase. _validate_slug() returns error message or None.
|
|
Additional check: `filepath.resolve().is_relative_to(vault_path.resolve())`.
|
|
Applied to both _log_session and _update_project_status.
|
|
- **Touches:** mcp/server.py
|
|
|
|
### Pydantic Settings
|
|
App configuration using pydantic-settings with LOOM_ env prefix. Covers
|
|
host, port, vault path, Trello credentials, and cache TTL. Reads from
|
|
.env file.
|
|
|
|
- **What:** `Settings` class with LOOM_ prefix and vault_dir property
|
|
- **Why:** Centralized config with env-file support
|
|
- **How:** pydantic-settings BaseSettings with env_prefix="LOOM_". vault_dir
|
|
is a @property that returns Path(vault_path).
|
|
- **Touches:** core/config.py
|