path: root/docs/sessions/create-session.org

#+TITLE: Creating New Session Workflows
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2025-11-01

* Overview

This document describes the meta-workflow for creating new session types. When we identify a repetitive workflow or collaborative pattern, we use this process to formalize it into a documented session that we can reference and reuse.

Session workflows are living documents that capture how we work together on specific types of tasks. They build our shared vocabulary and enable efficient collaboration across multiple work sessions.

* Problem We're Solving

Without a formal session creation process, we encounter several issues:

** Inefficient Use of Intelligence
- Craig leads the process based solely on his knowledge
- We don't leverage Claude's expertise to improve or validate the approach
- Miss opportunities to apply software engineering and process best practices

** Time Waste and Repetition
- Craig must re-explain the workflow each time we work together
- No persistent memory of how we've agreed to work
- Each session starts from scratch instead of building on previous work

** Error-Prone Execution
- Important steps may be forgotten or omitted
- No checklist to verify completeness
- Mistakes lead to incomplete work or failed goals

** Missed Learning Opportunities
- Don't capture lessons learned from our collaboration
- Can't improve processes based on what works/doesn't work
- Lose insights that emerge during execution

** Limited Shared Vocabulary
- No deep, documented understanding of what terms mean
- "Let's do a refactor session" has no precise definition
- Can't efficiently communicate about workflows

*Impact:* Inefficiency, errors, and lost opportunity to continuously improve our collaborative workflows.

* Exit Criteria

We know a session definition is complete when:

1. **Information is logically arranged** - The structure makes sense and flows naturally
2. **Both parties understand how to work together** - We can articulate the workflow
3. **Agreement on effectiveness** - We both agree that following this session will lead to exit criteria and resolve the stated problem
4. **Tasks are clearly defined** - Steps are actionable, not vague
5. **Problem resolution path** - Completing the tasks either:
   - Fixes the problem permanently, OR
   - Provides a process for keeping the problem at bay

*Measurable validation:*
- Can we both articulate the workflow without referring to the document?
- Do we agree it will solve the problem?
- Are the tasks actionable enough to start immediately?
- Does the session get used soon after creation (validation by execution)?

* When to Use This Session

Trigger this session creation workflow when:

- You notice a repetitive workflow that keeps coming up
- A collaborative pattern emerges that would benefit from documentation
- Craig says "let's create/define/design a session for [activity]"
- You identify a new type of work that doesn't fit existing session types
- An existing session type needs significant restructuring (treat as creating a new one)

Examples:
- "Let's create a session where we inbox zero"
- "We should define a code review session"
- "Let's design a session for weekly planning"

* Approach: How We Work Together

** Phase 1: Question and Answer Discovery

Walk through these four core questions collaboratively. Take notes on the answers.

*IMPORTANT: Save answers as you go!*

The Q&A phase can take time—Craig may need to think through answers, and discussions can be lengthy. To prevent data loss from terminal crashes or process quits:

1. Create a draft file at =docs/sessions/[name]-draft.org= after deciding on the name
2. After each question is answered, save the Q&A content to the draft file
3. If session is interrupted, you can resume from the saved answers
4. Once complete, the draft becomes the final session document

This protects against losing substantial thinking work if the session is interrupted.

*** Question 1: What problem are we solving in this type of session?

Ask Craig: "What problem are we solving in this type of session?"

The answer reveals:
- Overview and goal of the session
- Why this work matters (motivation)
- Impact/priority compared to other work
- What happens if we don't do this work

Example from refactor session:
#+begin_quote
"My Emacs configuration isn't resilient enough. There's lots of custom code, and I'm even developing some as Emacs packages. Yet Emacs is my most-used software, so when Emacs breaks, I become unproductive. I need to make Emacs more resilient through good unit tests and refactoring."
#+end_quote

*** Question 2: How do we know when we're done?

Ask Craig: "How do we know when we're done?"

The answer reveals:
- Exit criteria
- Results/completion criteria
- Measurable outcomes

*Your role:*
- Push back if the answer is vague or unmeasurable
- Propose specific measurements based on context
- Iterate together until criteria are clear
- Fallback (hopefully rare): "when Craig says we're done"

Example from refactor session:
#+begin_quote
"When we've reviewed all methods, decided which to test and refactor, run all tests, and fixed all failures including bugs we find."
#+end_quote

Claude might add: "How about a code coverage goal of 70%+?"

*** Question 3: How do you see us working together in this kind of session?

Ask Craig: "How do you see us working together in this kind of session?"

The answer reveals:
- Steps or phases we'll go through
- The general approach to the work
- How tasks flow from one to another

*Your role:*
- As steps emerge, ask yourself:
  - "Do these steps lead to solving the real problem?"
  - "What is missing from these steps?"
- If the answers aren't "yes" and "nothing", raise concerns
- Propose additions based on your knowledge
- Suggest concrete improvements

Example from refactor session:
#+begin_quote
"We'll analyze test coverage, categorize functions by testability, write tests systematically using Normal/Boundary/Error categories, run tests, analyze failures, fix bugs, and repeat."
#+end_quote

Claude might suggest: "Should we install a code coverage tool as part of this process?"

*** Question 4: Are there any principles we should be following while doing this?

Ask Craig: "Are there any principles we should be following while doing this kind of session?"

The answer reveals:
- Principles to follow
- Decision frameworks
- Quality standards
- When to choose option A vs option B

*Your role:*
- Think through all elements of the session
- Consider situations that may arise
- Identify what principles would guide decisions
- Suggest decision frameworks from your knowledge

Example from refactor session:
#+begin_quote
Craig: "Treat all test code as production code - same engineering practices apply."

Claude suggests: "Since we'll refactor methods mixing UI and logic, should we add a principle to separate them for testability?"
#+end_quote

** Phase 2: Assess Completeness

After the Q&A, ask together:

1. **Do we have enough information to formulate steps/process?**
   - If yes, proceed to Phase 3
   - If no, identify what's missing and discuss further

2. **Do we agree following this approach will resolve/mitigate the problem?**
   - Both parties must agree
   - If not, identify concerns and iterate

** Phase 3: Name the Session

Decide on a name for this session type.

*Naming convention:* Action-oriented (verb form)
- Examples: "refactor", "inbox-zero", "create-session", "review-code"
- Why: Shorter, natural when saying "let's do a [name] session"
- Filename: =docs/sessions/[name].org=

** Phase 4: Document the Session

Write the session file at =docs/sessions/[name].org= using this structure:

*** Recommended Structure
1. *Title and metadata* (=#+TITLE=, =#+AUTHOR=, =#+DATE=)
2. *Overview* - Brief description of the session
3. *Problem We're Solving* - From Q&A, with context and impact
4. *Exit Criteria* - Measurable outcomes, how we know we're done
5. *When to Use This Session* - Triggers, circumstances, examples
6. *Approach: How We Work Together*
   - Phases/steps derived from Q&A
   - Decision frameworks
   - Concrete examples woven throughout
7. *Principles to Follow* - Guidelines from Q&A
8. *Living Document Notice* - Reminder to update with learnings

*** Important Notes
- Weave concrete examples into sections (don't separate them)
- Use examples from actual sessions when available
- Make tasks actionable, not vague
- Include decision frameworks for common situations
- Note that this is a living document

** Phase 5: Update Project State

Update =NOTES.org=:
1. Add new session type to "Available Session Types" section
2. Include brief description and reference to file
3. Note creation date

Example entry:
#+begin_src org
,** inbox-zero
File: =docs/sessions/inbox-zero.org=

Workflow for processing inbox to zero:
1. [Brief workflow summary]
2. [Key steps]

Created: 2025-11-01
#+end_src

** Phase 6: Validate by Execution

*Critical step:* Use the session soon after creating it.

- Schedule the session type for immediate use
- Follow the documented workflow
- Note what works well
- Identify gaps or unclear areas
- Update the session document with learnings

*This validates the session definition and ensures it's practical, not theoretical.*

* Principles to Follow

These principles guide us while creating new sessions:

** Collaboration Through Discussion
- Be proactive about collaboration
- Suggest everything on your mind
- Ask all relevant questions
- Push back when something seems wrong, inconsistent, or unclear
- Misunderstandings are learning opportunities

** Reviewing the Whole as Well as the Pieces
- May get into weeds while identifying each step
- Stop to look at the whole thing at the end
- Ask the big questions: Does this actually solve the problem?
- Verify all pieces connect logically

** Concrete Over Abstract
- Use examples liberally within explanations
- Weave concrete examples into Q&A answers
- Don't just describe abstractly
- "When nil input crashes, ask..." is better than "handle edge cases"

** Actionable Tasks Over Vague Direction
- Steps should be clear enough to know what to do next
- "Ask: how do you see us working together?" is actionable
- "Figure out the approach" is too vague
- Test: Could someone execute this without further explanation?

** Validate Early
- "Use it soon afterward" catches problems early
- Don't let session definitions sit unused and untested
- Real execution reveals gaps that theory misses
- Update immediately based on first use

** Decision Frameworks Over Rigid Steps
- Sessions are frameworks (principles + flexibility), not recipes
- Include principles that help case-by-case decisions
- "When X happens, ask Y" is a decision framework
- "Always do X" is too rigid for most sessions

** Question Assumptions
- If something doesn't make sense, speak up
- If a step seems to skip something, point it out
- Better to question during creation than discover gaps during execution
- No assumption is too basic to verify

* Living Document

This is a living document. As we create new sessions and learn what works (and what doesn't), we update this file with:

- New insights about session creation
- Improvements to the Q&A process
- Better examples
- Additional principles discovered
- Refinements to the structure

Every time we create a session, we have an opportunity to improve this meta-process.

** Updates and Learnings

*** 2025-11-01: Save Q&A answers incrementally
*Learning:* During emacs-inbox-zero session creation, we discovered that Q&A discussions can be lengthy and make Craig think deeply. Terminal crashes or process quits can lose substantial work.

*Improvement:* Added guidance in Phase 1 to create a draft file and save Q&A answers after each question. This protects against data loss and allows resuming interrupted sessions.

*Impact:* Reduces risk of losing 10-15 minutes of thinking work if session is interrupted.

*** 2025-11-01: Validation by execution works!
*Learning:* Immediately after creating the emacs-inbox-zero session, we validated it by actually running the workflow. This caught unclear areas and validated that the 10-minute target was realistic.

*Key insight from validation:* When Craig provides useful context during workflows (impact estimates, theories, examples), that context should be captured in task descriptions. This wasn't obvious during session creation but became clear during execution.

*Impact:* Validation catches what theory misses. Always use Phase 6 (validate by execution) soon after creating a session.

* Example: Creating the "Create-Session" Session

This very document was created using the process it describes (recursive!).

** The Q&A
- *Problem:* Time waste, errors, missed learning from informal processes
- *Exit criteria:* Logical arrangement, mutual understanding, agreement on effectiveness, actionable tasks
- *Approach:* Four-question Q&A, assess completeness, name it, document it, update NOTES.org, validate by use
- *Principles:* Collaboration through discussion, review the whole, concrete over abstract, actionable tasks, validate early, decision frameworks, question assumptions

** The Result
We identified what was needed, collaborated on answers, and captured it in this document. Then we immediately used it to create the next session (validation).

* Conclusion

Creating session workflows is a meta-skill that improves all our collaboration. By formalizing how we work together, we:

- Build shared vocabulary
- Eliminate repeated explanations
- Capture lessons learned
- Enable continuous improvement
- Make our partnership more efficient

Each new session type we create adds to our collaborative toolkit and deepens our ability to work together effectively.

*Remember:* Sessions are frameworks, not rigid recipes. They provide structure while allowing flexibility for case-by-case decisions. The goal is effectiveness, not perfection.