tzurot-docs

lbds137's avatarfrom lbds137

Documentation maintenance for Tzurot v3 - Updating CURRENT_WORK.md, folder structure, and keeping docs current. Use at session end or when documentation needs updating.

⭐7stars🔀1forks📁View on GitHub🕐Updated Jan 2, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the maintenance of technical documentation and project state, specifically optimized for the Tzurot v3 framework. It ensures that critical files like CURRENT_WORK.md, CLAUDE.md, and ROADMAP.md remain accurate, while managing a sophisticated 'Time-State Architecture' for documentation folders. By enforcing strict documentation protocols and session handoff procedures, it solves the problem of stale documentation and context loss in long-term development projects.

Use Cases

  • Session Handoff & Context Preservation: Automatically updating CURRENT_WORK.md at the end of a coding session to document progress, current phase, and next steps for a seamless restart.
  • Documentation Lifecycle Management: Moving feature ideas from 'proposals' to 'reference' once implemented, and ensuring obsolete documents are deleted to prevent information bloat.
  • Project Structure Standardization: Organizing technical docs into a predefined hierarchy (reference, proposals, incidents, migration) to maintain a clean and navigable knowledge base.
  • Guideline Alignment: Updating CLAUDE.md with new coding patterns, conventions, or architectural decisions to ensure the AI assistant remains aligned with the project's evolving standards.
nametzurot-docs
descriptionDocumentation maintenance for Tzurot v3 - Updating CURRENT_WORK.md, folder structure, and keeping docs current. Use at session end or when documentation needs updating.
lastUpdated'2026-01-04'

Tzurot v3 Documentation Maintenance

Use this skill when: Ending a session, completing a milestone, creating new documentation, or updating existing docs.

Quick Reference

# CURRENT_WORK.md format

> Last updated: YYYY-MM-DD

## Status: [Brief description of current focus]

**Current Phase**: [What you're actively working on]

**Recent Completion**: [Major milestone just finished]

## Active Work

[Details of current task]

## Planned Features (Priority Order)

[Upcoming work]

Core Documentation Files

File Purpose Update When
CURRENT_WORK.md Active work status Start/end session, milestone
CLAUDE.md Project guidelines New patterns, conventions
ROADMAP.md Planning roadmap Sprint changes
GitHub Releases Version history Each release

Root files only: README.md, CLAUDE.md, CURRENT_WORK.md, ROADMAP.md. Everything else → docs/

Documentation Structure (Time-State Architecture)

docs/
├── reference/           # THE TRUTH - What currently exists
│   ├── architecture/    # Design decisions, system architecture
│   ├── deployment/      # Railway, infrastructure setup
│   ├── operations/      # Runbooks, backup procedures
│   ├── standards/       # Coding patterns, folder structure
│   ├── guides/          # Developer how-tos
│   ├── features/        # Feature documentation
│   ├── testing/         # Test procedures
│   ├── database/        # Schema documentation
│   └── templates/       # Reusable document templates
├── proposals/           # THE PLANS - What we want to build
│   ├── active/          # On roadmap, being worked on
│   └── backlog/         # Ideas not yet scheduled
├── incidents/           # Postmortems and lessons learned
└── migration/           # Active migration guides

Decision Rules

Question Answer
Is it implemented? → reference/
Is it a plan/idea? → proposals/ (active or backlog)
Is it done/obsolete? → Extract learnings, then DELETE
Is it an incident? → incidents/

Proposal Lifecycle

  1. New idea → proposals/backlog/
  2. Scheduled for work → Move to proposals/active/
  3. Implementation complete:
    • Extract learnings to reference/ docs or skills
    • Update incident docs if issues found
    • DELETE the proposal (git preserves history)

Session Handoff Protocol

At session end:

  1. Update CURRENT_WORK.md with progress
  2. Delete obsolete docs (git history preserves them)
  3. Update doc timestamps if modified
# Get current date
date +%Y-%m-%d

# Commit WIP if needed
git commit -m "wip: feature-name - progress description"

Best Practices

✅ Do

  • Use descriptive names: memory-and-context-redesign.md
  • Update existing docs instead of creating new ones
  • Use YYYY-MM-DD date format
  • Link between related docs with relative paths
  • Delete obsolete docs (git preserves history)
  • Use frontmatter for dates, not filenames

❌ Don't

  • Create documentation bloat (one topic = one doc)
  • Let CURRENT_WORK.md get stale
  • Create README files in every directory
  • Document obvious things
  • Keep archive folders (delete instead)
  • Put dates in filenames

Documentation Categories

Type Location Purpose
Architecture decisions docs/reference/architecture/ Why we built it this way
Deployment guides docs/reference/deployment/ Railway setup, operations
Development guides docs/reference/guides/ How to do X
Coding standards docs/reference/standards/ Patterns to follow
Active proposals docs/proposals/active/ Currently being worked
Future ideas docs/proposals/backlog/ Not yet scheduled
Post-mortems docs/incidents/ Incident analysis

GitHub Releases Format

## What's Changed

### Added

- New feature X for doing Y

### Changed

- Improved performance of A by 50%

### Fixed

- Bug where X would fail under Y conditions

**Full Changelog**: https://github.com/lbds137/tzurot/compare/vX.X.X...vY.Y.Y

Note: This project uses GitHub Releases, NOT CHANGELOG.md.

Anti-Patterns

❌ Don't ✅ Do
Multiple docs for same topic One comprehensive guide
Stale CURRENT_WORK.md Update at session end
README in every directory One main README
Document obvious things Document non-obvious
Archive obsolete docs Delete (extract learnings first)
Date-stamped filenames Frontmatter dates

Context Preservation

For AI sessions, always check these at session start:

  1. CURRENT_WORK.md - What's happening now?
  2. CLAUDE.md - What are the rules?
  3. docs/README.md - What docs exist?
  • tzurot-git-workflow - Commit documentation updates
  • tzurot-council-mcp - When to consult for doc structure
  • tzurot-architecture - Document architectural decisions

References

  • Documentation structure: docs/README.md
  • Current project status: CURRENT_WORK.md
  • Project guidelines: CLAUDE.md
  • Tech debt tracking: docs/proposals/active/TECH_DEBT.md