session-discipline
Enforce session-first workflow (plan → implement → verify → document). Use whenever starting non-trivial work, debugging >15 minutes, or doing cross-cutting changes.
When & Why to Use This Skill
The Session Discipline skill enforces a rigorous, session-first workflow—Plan, Implement, Verify, and Document—to ensure all non-trivial tasks are traceable, organized, and resumable. By standardizing the creation of session logs and planning documents, it minimizes context loss, reduces handover friction, and maintains a high-quality knowledge base for complex software development and debugging projects.
Use Cases
- Complex Feature Implementation: Use when initiating non-trivial development tasks to ensure a clear objective, change set, and risk assessment are documented in PLAN.md before execution.
- Extended Debugging Sessions: Apply when a bug takes more than 15 minutes to resolve, creating a structured log of commands and findings in WORKING_NOTES.md to prevent circular troubleshooting.
- Cross-Cutting System Changes: Manage architectural or multi-module modifications by maintaining a centralized session folder that tracks all impacted files and verification outcomes.
- Team Collaboration and Handovers: Streamline the transition of tasks between developers or agents by providing a discoverable history of actions and deferred follow-ups in a standardized format.
- Audit and Compliance: Maintain a permanent record of 'why' and 'how' changes were made, ensuring every action is backed by evidence and discoverable within the project's documentation hub.
| name | session-discipline |
|---|---|
| description | Enforce session-first workflow (plan → implement → verify → document). Use whenever starting non-trivial work, debugging >15 minutes, or doing cross-cutting changes. |
Session Discipline
Scope
- Ensure every non-trivial task has a session folder under
docs/sessions/ - Keep evidence (commands/tests) and outcomes discoverable
- Reduce “handover friction” by making every action resumable from docs
Inputs
- Desired session slug (short, descriptive)
- Session type/category and objective one-liner
Procedure
- Create a session directory with the official CLI.
- Fill in
PLAN.md(objective, done-when, change set, risks, tests). - Log commands + findings in
WORKING_NOTES.md. - Summarize outcomes + follow-ups with named owners.
Validation
- Confirm session appears in
docs/sessions/SESSIONS_HUB.md. - Ensure
FOLLOW_UPS.mdhas owners if anything is deferred.
Escalation / Research request
If you need deeper background and existing docs aren’t sufficient:
- Add a follow-up: “Request research agent to expand Skill ”
- Include: expected triggers, target files, and what validation should exist
References
- Session-first requirement:
AGENTS.md - docs-memory lessons:
docs/agi/LESSONS.md