.sit/ Directory Structure Guide

This directory contains reference materials, implementation guides, proposals, and reports for the project. It is organized to help AI agents and developers quickly find the right place to read from or write documentation.

The Study → Propose → Implement → Reflect Cycle

Steps in Time follows a four-phase workflow for AI-assisted development:

Phase 1: Study

Before writing code, gather context from the .sit/ hierarchy:

1. Review docs/ — Understand the high-level architecture and technologies
2. Consult howto/ — Find concise guides with proven patterns and code snippets
3. Examine reports/ — Learn from past retrospectives, bugs, and test results

Phase 2: Propose

1. Create/update proposals/ — Document the design before implementation
2. Consult howto/ - Find relevant code snippets proved to work in the past
3. Plan/(Pseudo)code - Add relevant code snippets to proposals/ to be followed closely

Phase 3: Implement

1. Implement — Write code following patterns from proposal/

Phase 4: Reflect

1. Write reports/ — Document outcomes, discrepancies, and lessons learned
2. Update howto/ — Refine guides based on what actually worked
3. Deprecate proposals — Move completed proposals with implementation notes

This cycle ensures knowledge accumulates rather than being lost between sessions.

Document Interdependence

The four directories form a knowledge pipeline that maps directly to the workflow phases:

                    ┌──────────────────────────────────────────┐
                    │              REFLECT                     │
                    ▼                                          │
┌─────────┐    ┌─────────┐    ┌───────────┐    ┌─────────┐    │
│  docs/  │───▶│ howto/  │───▶│proposals/ │───▶│reports/ │────┘
│         │    │         │    │           │    │         │
│ concepts│    │ patterns│    │  designs  │    │ lessons │
└─────────┘    └─────────┘    └───────────┘    └─────────┘
     │              ▲              │                │
     │   STUDY      │    PROPOSE   │    REFLECT     │
     │              └──────────────┴────────────────┘
     └───────────────────── STUDY ─────────────────────▶

How Documents Feed Each Other

Cross-Reference Requirements

When creating documents, always link to related documents:

• proposals/ must reference relevant docs/ and howto/ consulted during design
• reports/ must reference the proposals/ being evaluated
• howto/ should cite reports/ that validated the patterns
• docs/ should link to howto/ for practical implementation

Learning from Mistakes

The most valuable insights come from analyzing discrepancies between proposals and final outcomes. This section describes how to systematically capture and learn from mistakes.

Extracting Lessons via Git History

When a proposal is implemented, compare what was planned versus what actually happened. The proposal file itself is the primary source of truth—its git history reveals how understanding evolved during implementation.

# Track how the proposal evolved during implementation
git log --oneline -- .sit/proposals/<feature>.md

# See what changed in the proposal over time
git log -p -- .sit/proposals/<feature>.md

# Compare the original proposal to its final state
git diff <first-commit>..<last-commit> -- .sit/proposals/<feature>.md

The proposal’s revision history answers critical questions:

• What was added? — Scope creep, discovered requirements
• What was removed? — Deferred features, abandoned approaches
• What was rewritten? — Misunderstandings corrected mid-implementation

# Find implementation commits related to a proposal
git log --oneline --all --grep="feature-name"

# Compare proposal date to implementation commits
git log --after="2025-01-01" --before="2025-02-01" -- path/to/feature/

# See what files changed vs. what was expected
git diff <proposal-commit>..<implementation-commit> --stat

Discrepancy Categories

Document these types of discrepancies in reports:

The Mistake → Knowledge Pipeline

1. MISTAKE OCCURS
   └─▶ Bug found, test fails, approach doesn't work

2. DOCUMENT IN REPORT
   └─▶ reports/YYYY-MM-DD_<event>.md
       - What happened
       - Root cause analysis
       - How it was resolved

3. UPDATE PROPOSAL (if applicable)
   └─▶ proposals/.deprecated/<feature>.md
       - Add "Lessons Learned" section
       - Document discrepancies from plan

4. REFINE HOWTO
   └─▶ howto/<pattern>.md
       - Add to "Common Pitfalls" section
       - Update patterns that failed
       - Add patterns that worked

5. UPDATE DOCS (if architectural insight)
   └─▶ docs/<component>.md
       - Correct misconceptions
       - Add constraints discovered

Report Template: Lessons Learned Section

Every report should include a structured “Lessons Learned” section:

## Lessons Learned

### What Went Well
- [Pattern/approach that worked as expected]
- [Decision that proved correct]

### What Went Wrong
- [Mistake/bug/issue encountered]
- [Root cause identified]

### Discrepancies from Proposal
- **Planned:** [What proposal said]
- **Actual:** [What implementation required]
- **Why:** [Reason for discrepancy]

### Recommendations
- [ ] Update `howto/<guide>.md` with [specific pattern]
- [ ] Add warning to `docs/<component>.md` about [constraint]
- [ ] Future proposals should consider [factor]

Mistake Patterns to Watch For

Track recurring mistake patterns across reports:

1. Estimation errors — Features consistently take longer than planned
2. Integration surprises — External dependencies behave unexpectedly
3. Test coverage gaps — Bugs escape to production in similar areas
4. Architecture drift — Implementation diverges from documented architecture
5. Pattern misapplication — Howto guides used in wrong contexts

When a pattern appears 3+ times, create or update a howto/ guide addressing it.

Directory Overview

.sit/
├── docs/          # Reference documentation (for understanding)
├── howto/         # Implementation guides (for doing)
├── proposals/     # Future plans and designs (for planning)
└── reports/       # Post-mortem analyses and test results (for learning)

Each directory has a .deprecated/ subdirectory for documents that are no longer current but may be historically valuable.

docs/ - Reference Documentation

Purpose: Documentation about the project and its dependencies for understanding how things work.

When to write here:

• User-facing documentation explaining project features
• Technical architecture overviews
• Third-party library documentation
• Conceptual explanations of system components
• API reference documentation

When NOT to write here:

• Step-by-step implementation guides (use howto/)
• Proposals for future features (use proposals/)
• Test results or bug post-mortems (use reports/)

Examples of documents:

• docs/architecture/overview.md - System architecture overview
• docs/libraries/some-library/reference.md - Library reference documentation

Subdirectories:

• Organize by component, library, or feature area as needed

Deprecated directory: .deprecated/

• Move here: Documentation about removed features or outdated architectural patterns
• Example: If the project removes a feature, move its docs here with a note explaining why

howto/ - Implementation Guides

Purpose: Step-by-step guides for implementing features or patterns in the project.

When to write here:

• “How to implement X” guides for developers
• Architectural patterns to follow when building features
• Best practices for specific implementation tasks
• Workflow guides for common development scenarios

When NOT to write here:

• Conceptual documentation (use docs/)
• Future proposals (use proposals/)
• Test results (use reports/)

Examples of documents:

• howto/e2e_testing_guide.md - Complete guide to writing E2E tests
• howto/authentication_implementation.md - Guide to implementing authentication

Characteristics of a good howto:

• Actionable steps (numbered lists, code examples)
• Clear use cases (“Use this pattern when…”)
• Pitfalls and common mistakes section
• Example implementations from the codebase

Deprecated directory: .deprecated/

• Move here: Guides that describe outdated implementation patterns
• Example: Old implementation guide after a major refactor introduces new patterns

AI Agent Guidance:
When a user asks “how do I implement X?”, check howto/ first before writing new documentation. If the pattern exists but is outdated, update the existing document instead of creating a new one.

proposals/ - Future Plans and Designs

Purpose: Design documents for future features or improvements that are not yet implemented. Proposals should include concrete code snippets from howto/ that will be followed during implementation.

When to write here:

• Feature proposals (before implementation begins)
• Architecture redesign proposals
• Performance optimization plans
• Security enhancement proposals

Key principle: A proposal is not just prose—it should contain the actual code patterns to follow. During the Propose phase, pull relevant snippets from howto/ into the proposal so the Implement phase becomes execution rather than discovery.

When NOT to write here:

• Implemented features (move to proposals/.deprecated/)
• Implementation guides (use howto/)
• Test results (use reports/)

Document lifecycle:

1. Active proposal: Lives in proposals/ during planning and implementation
2. Implemented proposal: Moved to proposals/.deprecated/ when complete
3. Update status: Add implementation status, commits, and lessons learned before moving

Required fields in proposal:

**Status**: [Planning | In Progress | Complete | Abandoned]
**Date:** YYYY-MM-DD
**Priority:** [Critical | High | Medium | Low]
**Implementation:** [Date range or TBD]
**Commits:** [List of commit hashes when implemented]

Examples of documents:

• proposals/new_feature_design.md - Feature proposal (status: Planning)
• proposals/.deprecated/completed_feature.md - Implemented feature (status: Implemented)

Deprecated directory: .deprecated/

• Move here: Completed proposals (with implementation details) or abandoned proposals
• IMPORTANT: Update the proposal with implementation results before moving:
  • Add commit hashes
  • Document lessons learned
  • Update status to “Implemented” or “Abandoned”
  • Add references to related reports if applicable

AI Agent Guidance:

• When starting implementation of a proposal, mark status as “In Progress”
• When completing implementation, update the proposal with commits and lessons learned, then move to .deprecated/
• If a proposal is abandoned, document why before moving to .deprecated/
• Before creating a new proposal, check both proposals/ and proposals/.deprecated/ to avoid duplicating previous work

reports/ - Post-Mortem Analyses and Test Results

Purpose: Reports documenting past events, test results, bug analyses, and implementation retrospectives.

When to write here:

• Load testing results and performance benchmarks
• Bug post-mortems (root cause analysis)
• E2E test reports for specific features
• Implementation retrospectives (what went well/wrong)
• Security audit results

When NOT to write here:

• Ongoing proposals (use proposals/)
• Implementation guides (use howto/)
• General documentation (use docs/)

Naming convention:

YYYY-MM-DD_descriptive_name.md

Examples:

• 2025-11-06_load_testing_results.md
• 2025-10-28_authentication_bug_fix.md

Required sections in report:

• Date: When the event/test occurred
• Summary: High-level overview (1-2 paragraphs)
• Context: What led to this report
• Findings: Detailed results, bugs discovered, metrics
• Resolution: How issues were fixed (if applicable)
• Lessons Learned: Key insights for future work

Examples of documents:

• reports/2025-11-06_load_testing_results.md - Comprehensive load testing analysis
• reports/2025-10-29_feature_test_results.md - E2E test results for a feature

Deprecated directory: .deprecated/

• Move here: Reports that are superseded by newer testing or no longer relevant to current codebase
• Example: Old performance baseline when architecture changes make it irrelevant

AI Agent Guidance:

• Always include date in filename for chronological sorting
• Cross-reference related proposals
• When fixing bugs found in testing, link commits back to the report
• If a report describes a critical bug, ensure project documentation is updated with prevention patterns

Working with .deprecated/ Directories

Every main directory has a .deprecated/ subdirectory for documents that are no longer current.

When to deprecate a document:

docs/.deprecated/

• Documentation about removed features
• Outdated architectural explanations
• Superseded library documentation

howto/.deprecated/

• Implementation guides for removed patterns
• Obsolete workflow instructions
• Guides contradicting new best practices

proposals/.deprecated/

• Implemented proposals (most common)
• Abandoned proposals (with explanation)
• Superseded proposals (replaced by better designs)

reports/.deprecated/

• Reports about resolved issues no longer relevant
• Superseded testing results (when new tests invalidate old baseline)
• Historical reports kept for reference but not actively consulted

How to deprecate:

1. Update the document:
   • Add deprecation notice at the top
   • Explain why it’s deprecated
   • Link to replacement document if applicable
2. Move to .deprecated/:

   git mv .sit/category/doc.md .sit/category/.deprecated/doc.md
   

3. Update references:
   • Search codebase for links to the deprecated document
   • Update links to point to new location or replacement

AI Agent Guidance:

• Never delete documents—always deprecate them instead
• When deprecating, always add context (why? what replaced it?)
• Check for references before deprecating (use Grep tool)

Decision Tree for AI Agents

When creating or updating documentation, use this decision tree:

┌─ Is this about HOW something works?
│  └─ YES → .sit/docs/
│
├─ Is this about HOW TO IMPLEMENT something?
│  └─ YES → .sit/howto/
│
├─ Is this about FUTURE plans or designs?
│  └─ YES → .sit/proposals/
│
└─ Is this about PAST events, tests, or bugs?
   └─ YES → .sit/reports/

Examples:

AI Agent Responsibilities

When working with .sit/, AI agents should follow the four-phase workflow:

Phase 1: Study (Before Proposing)

1. Read docs/ to understand architecture and constraints
2. Consult howto/ for proven implementation patterns
3. Examine reports/ to learn from past mistakes
4. Search .deprecated/ to avoid recreating obsolete patterns

Phase 2: Propose (Before Implementing)

1. Create proposal in proposals/ with status “Planning”
2. Copy code snippets from relevant howto/ guides into proposal
3. Include actual patterns to follow, not just descriptions
4. Cross-reference the docs and howtos consulted

Phase 3: Implement (During Coding)

1. Follow the proposal closely—deviations signal learning opportunities
2. Update proposal when reality diverges from plan
3. Mark status as “In Progress”

Phase 4: Reflect (After Implementation)

1. Write report documenting outcomes and discrepancies
2. Update proposal with implementation notes and lessons learned
3. Refine howto/ based on what actually worked
4. Move proposal to .deprecated/ with final status
5. Review proposal git history to capture how understanding evolved

When Deprecating:

1. Add deprecation notice explaining why
2. Move to .deprecated/ subdirectory using git mv
3. Update cross-references in other documents
4. Never delete historical documents

Integration with Project Documentation

The .sit/ directory complements main project documentation (e.g., README.md, CONTRIBUTING.md):

• Main docs: Quick reference for active development (commands, patterns, architecture)
• .sit/docs/: Deep-dive documentation about system components
• .sit/howto/: Detailed implementation guides
• .sit/proposals/: Historical record of design decisions
• .sit/reports/: Evidence supporting best practices

Workflow:

1. Main docs point to detailed guides in .sit/howto/
2. Reports validate or invalidate patterns in main docs
3. Proposals explain why current architecture exists
4. Docs provide background for concepts mentioned in main docs

Template: Creating New Documents

For .sit/docs/

# [Component/Feature Name]

**Last Updated:** YYYY-MM-DD

## Overview
[What this component is and why it exists]

## Architecture
[How it works]

## Key Concepts
[Important ideas to understand]

## References
[Links to code, proposals, reports]

For .sit/howto/

# How to Implement [Feature/Pattern]

**Last Updated:** YYYY-MM-DD

## When to Use This Pattern
[Scenarios where this applies]

## Prerequisites
[What you need to know/have]

## Implementation Steps
1. [Step with code example]
2. [Step with code example]

## Testing
[How to verify implementation]

## Common Pitfalls
[What to avoid]

## Examples
[Real implementations in codebase]

For .sit/proposals/

# [Feature/Improvement Name]

**Status**: [Planning | In Progress | Complete | Abandoned]
**Date:** YYYY-MM-DD
**Priority:** [Critical | High | Medium | Low]
**Implementation:** [Date or TBD]
**Commits:** [Hash list or N/A]

## Summary
[One paragraph explaining the proposal]

## Problem Statement
[What problem this solves]

## Proposed Solution
[How to solve it]

## Implementation Plan
[Phases, tasks]

## Code Patterns to Follow
[Copy relevant snippets from howto/ guides here. These become the
blueprint for implementation—not suggestions, but the actual code
structure to use.]

### From howto/<guide>.md:
```[language]
[Actual code snippet to follow]

Risks & Mitigations

[What could go wrong and how to handle it]

[Added after implementation]

Implementation Notes:
[What changed during implementation]

Lessons Learned:
[Key insights from the process]

Proposal Revisions:
[Summary of how the proposal changed during implementation—
see git log for this file]

### For .sit/reports/
```markdown
# [Event/Test Name]

**Date:** YYYY-MM-DD
**Duration:** [Time span]
**Result:** [Summary: Pass, Issues Found, Fail]

## Summary
[High-level overview]

## Context
[Why this test/event occurred]

## Findings
[Detailed results, bugs, metrics]

## Resolution
[How issues were fixed]

## Files Modified
[List with brief descriptions]

## Lessons Learned
[Key insights]

## Recommendations
[What to do next]

Quick Reference

Maintenance

For comprehensive maintenance routines using steps-in-time’s introspection tools, see:

📖 Chore Routine Guide

Covers:

• Daily checks (verification scan, implementation log)
• Weekly health (KB velocity, link conventions, token costs)
• Monthly trends (regression analysis, retrospective metrics)
• Quarterly reviews (late retrospectives, pattern audits)

Quick Checks

# Weekly: KB health dashboard
mcp__plugin_sit_steps-in-time__health_check(format: "markdown")

# Weekly: Link convention violations
/sit:linkconv

# Monthly: Workflow metrics comparison
sit analyze regression --list

Last Updated: 2026-01-19