Session Logger

Codex Rule References

Codex-native logging and handoff should explicitly apply:

• .claude/rules/docs/documentation.md
• .claude/rules/communication.md
• .claude/rules/output-format.md

Session Log Template

# {YYYY-MM-DD} {feature-name} Session

## Metadata
- Start/End: {HH:MM} - {HH:MM}
- Branch: {branch}
- Main work: {summary}

## Timeline
### [HH:MM] Event
- Details...

## Decision Log
| Time | Decision | Reason | Alternative |
|------|----------|--------|-------------|

## Issue Log
### Issue #N: {title}
- Problem / Cause / Fix / Prevention

## Fix Forward Tasks
| Issue | Severity | File | Suggestion | Status |
|-------|----------|------|------------|--------|
| {from codex-review-code fixForward.tasks[]} | HIGH | {file} | {suggestion} | ⏳ Pending |

## Retrospective
- What went well / What to improve / Lessons

Session Handoff (HANDOFF.md)

When context window is over 80% full:

1. If analysisContext.artifacts.handoffPath exists, use that path; otherwise create {tasksRoot}/{feature-name}/HANDOFF.md
2. Run /clear
3. Load HANDOFF.md in new session

HANDOFF.md Template:

# {Task} - Handoff

## Goal
{Current objective}

## Progress
- Done: ...
- Worked: ...
- Failed: ... (reason)

## Fix Forward Tasks (Carry Over)
| Issue | Severity | File | Suggestion |
|-------|----------|------|------------|
| {pending fix-forward tasks from this session} |

## Next Steps
1. Resolve fix-forward tasks above (if any)
2. ...

## Context
- Files: {paths}
- Branch: {branch}
- Last commit: {hash}

File Structure

Preferred shared daily log structure:

docs/daily/
└── YYYY-MM-DD/
    ├── codex.md
    ├── claude.md
    └── kimi.md

Task-local fallback structure:

{tasksRoot}/{feature-name}/
├── HANDOFF.md
└── session-logs/
    ├── day-YYYY-MM-DD.md
    └── ...

Execution-bridge variant:

{tasksRoot}/{feature-name}/execution/{slice-name}/
├── SPRINT_CONTRACT.md
├── QA_REPORT.md
└── HANDOFF.md

Tips

1. Auto-create at work start
2. Real-time updates on each agent switch
3. Token limit: Keep daily logs under 5000 tokens
4. Resume: Review previous log before continuing

Memory Integration (Optional)

Only active when MCP Memory is configured.

Solution Promotion

When a session captures a reusable remediation pattern:

1. identify whether the lesson meets the promotion rules in .claude/docs/solutions/README.md
2. create or update a solution asset under .claude/docs/solutions/
3. record the source artifacts that justified the promotion

Promote when:

• retries exposed a reusable fix pattern
• the verification recipe should be reused later
• the lesson changes future plan or guardrail decisions