From 697f7d1946f30cbeafd24ad0b4faa3a6dbd985f6 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Tue, 16 Sep 2025 22:06:41 +0800
Subject: [PATCH] refactor: Update session tracking documentation for clarity
 and consistency

---
 CLAUDE.md | 80 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 59 insertions(+), 21 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index ed25053b2..726c59f5e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,45 +14,83 @@ This file provides guidance to AI coding assistants when working with code in th
 1.  **Code Search**: Use `ast-grep` for semantic code pattern searches when available. Fallback to `rg` (ripgrep) or `grep` for text-based searches.
 2.  **UI Framework**: Exclusively use **HeroUI** for all new UI components. The use of `antd` or `styled-components` is strictly **PROHIBITED**.
 3.  **Quality Assurance**: **Always** run `yarn build:check` before finalizing your work or making any commits. This ensures code quality (linting, testing, and type checking).
-4.  **Session Documentation**: MUST Consistently maintain the session SDLC log file following the template structure outlined in the Session Tracking section.
+4.  **Session Tracking Documentation**: MUST Consistently maintain the session SDLC log file following the template structure outlined in the Session Tracking section.
 5.  **Centralized Logging**: Use the `loggerService` exclusively for all application logging (info, warn, error levels) with proper context. Do not use `console.log`.
 6.  **External Research**: Leverage `subagent` for gathering external information, including latest documentation, API references, news, or web-based research. This keeps the main conversation focused on the task at hand.
 
-## Session Tracking
+## Session Tracking Protocol
 
-ALWAYS maintain a session log in `.sessions/YYYY-MM-DD-HH-MM-SS-<feature>.md`. This is critical for tracking progress and decisions:
+Purpose: keep a living SDLC record so any coding agent can pause or resume work without losing momentum.
 
+### When to Log
+- Start a new file when kicking off a feature or major task branch.
+- Append to the existing file whenever you switch focus, finish a task, encounter a blocker, or hand over.
+- If you resume someone else's session, add a new patch log entry summarizing what you picked up and what remains.
+
+### File Naming
+- `.sessions/YYYYMMDD-<feature>.md`
+- Example: `.sessions/20250916-agent-onboarding.md`
+
+### Template
 ```md
-# <feature> — SDLC Session (<YYYY-MM-DD HH:MM>)
+# <feature> — SDLC Session (<YYYY-MM-DD>)
+
+## Session Metadata
+- Participants:
+- Repo state / branch:
+- Related tickets / docs:
+- Links to prior sessions:
 
 ## Design Brief
 - Problem & goals:
-- Non-goals/scope:
+- Non-goals / scope:
 - Constraints & risks:
 - Acceptance criteria:
 
-## Solution Design
-- Architecture/flow:
-- Key interfaces:
-- Data model:
+## Solution Plan
+- Architecture / flow:
+- Key interfaces or modules:
+- Data considerations:
 - Test strategy:
 
 ## Work Plan
-| ID  | Task | Owner | Depends | Est | Status |
-| --- | ---- | ----- | ------- | --- | ------ |
-| T1  |      |       |         |     | TODO   |
+| ID  | Task | Owner | Depends | Est | Status | Notes |
+| --- | ---- | ----- | ------- | --- | ------ | ----- |
+| T1  |      |       |         |     | TODO   |       |
 
-## Patch Log
-### <HH:MM>
-- Summary:
-- Files:
-- Tests/Commands:
-- Next:
+_Status values: TODO, IN PROGRESS, BLOCKED, DONE. Update estimates as work evolves._
+
+## Execution Log
+### <YYYY-MM-DD HH:MM>
+- Activity summary (what changed, decisions made)
+- Artifacts (PRs, commits, file paths, specs)
+- Tests / Commands run:
+- Issues / Risks:
+- Next focus before handoff:
+
+_Append a new timestamped block for each meaningful work segment._
+
+## Handoff Checklist
+- [ ] Remaining work captured in Work Plan
+- [ ] Blockers / questions called out
+- [ ] Links to diffs / PRs / relevant artifacts
+- [ ] Next session entry point documented
 
 ## Validation
-- [ ] Criteria met
-- [ ] build:check passes
-- [ ] Tests green
+- [ ] Acceptance criteria met
+- [ ] `yarn build:check` passes
+- [ ] Tests required by strategy green
+- [ ] Docs / tickets updated (if applicable)
+```
+
+### Usage Example
+```
+### 2025-09-16 18:40
+- Activity: Finished wiring HeroUI settings panel skeleton; left TODO for data bindings.
+- Artifacts: src/renderer/.../SettingsPanel.tsx, PR #1234 (draft).
+- Tests / Commands: yarn lint
+- Issues / Risks: Waiting on API schema (#456).
+- Next focus: Bind `updateSettings` once API lands; run yarn build:check before flip to PR.
 ```