forge-openclaw-plugin 0.2.23 → 0.2.25

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -1,70 +1,116 @@
 # Entity Conversation Playbooks
 
 Use this file whenever the user is creating or updating a Forge entity outside the
-deeper Psyche exploration flow. The point is to keep the conversation natural and
-intentional while still gathering enough structure to store the right record.
+deeper Psyche exploration flow. The goal is not to walk through a form. The goal is to
+help the user recognize what they are trying to save, name it cleanly, place it in
+Forge correctly, and gather only the structure that still matters.
 
-## Interaction stance
+## Core stance
 
 - Ask only for what is missing or still unclear.
-- Lead the user somewhere. Know whether you are trying to clarify the name, the role,
-  the outcome, the placement, the timing, the success condition, or the links.
-- Let each question have one job. If you cannot say what the question is trying to
-  clarify, ask a different question.
-- Ask one to three focused questions at a time. One is usually best when the user is
-  unsure or emotionally loaded.
-- Reflect briefly before the next question when the user gives nuance that matters.
-- For emotionally meaningful planning records such as goals, habits, and notes, reflect
-  the meaning first and then ask for the structure.
-- Do not read schema fields out loud unless the user explicitly wants a mechanical
-  checklist.
-- Prefer a progression of:
-  recent intent or concrete example -> working name -> purpose or outcome -> placement
-  in Forge -> operational details -> linked context.
-- If the user already gave a usable title, timing, or parent context, do not ask for it
-  again just because the schema has that field.
-- When the user says "save something about..." and the record is still fuzzy, help them
-  sharpen what they are trying to preserve before you ask for the final Forge shape.
+- Before every question, decide the one missing thing you are trying to clarify.
+- Know where the conversation is headed before you ask the next question.
+- Prefer one clean question to a stacked sentence with several asks.
+- Reflect briefly when the user gives meaning, ambivalence, or emotionally loaded
+  context that matters to the record.
+- Especially for goals, habits, notes, and updates, reflect what the user is trying to
+  preserve, change, or make true before you ask for structure.
+- For emotionally meaningful non-Psyche records such as goals, habits, notes, and many
+  updates, use a simple rhythm:
+  brief reflection -> one orienting question.
+- Another good shorthand for the same rhythm is:
+  short reflection -> one orienting question.
+- For straightforward logistical entities such as tasks, calendar events, work blocks,
+  timeboxes, and task runs, use a fast path:
+  one brief confirming sentence -> one operational question.
+- For logistical records such as tasks, calendar events, work blocks, timeboxes, and
+  task runs, use a fast path:
+  one brief confirming sentence -> one operational question.
+- Do not read schema fields out loud unless the user explicitly wants a checklist.
+- Do not ask the user to do naming work alone when the meaning is already clear. Offer
+  a tentative title or formulation and invite correction.
 - When the meaning is clearer than the wording, offer a tentative title or summary
-  yourself and ask whether it fits. Do not make the user do all the naming work alone.
-- Before saving, offer a short working summary in the user's own language when that
-  would reduce ambiguity.
-- When updating, start with:
-  what is changing,
-  what should stay true,
-  and what prompted the update now.
+  yourself and ask whether it fits.
+- If the user already answered the usual opening question, do not repeat the stock
+  opener. Move straight to the next missing clarification.
+- Once the record is clear enough to name, stop exploring broadly and ask only for the
+  last missing structural detail.
+
+## Conversation arc
+
+Most good Forge intake flows follow this sequence:
+
+1. Clarify what the user is trying to preserve, change, or make true.
+2. Land on the right Forge shape.
+3. Offer or confirm a working name.
+4. Clarify the outcome, placement, timing, or cadence that will matter later.
+5. Ask about links only when those links will make the record more useful.
+
+That sequence is not a script. Skip steps the user already answered.
+
+## Active-listening patterns
+
+Use one of these shapes when the user is not yet precise.
+
+Meaning-bearing record:
+
+- "It sounds like you want to keep hold of something important here. What feels most
+  worth preserving about it?"
+
+Bounded-work record:
+
+- "So this is becoming a real piece of work, not just a passing idea. What outcome
+  would make it feel real or complete for now?"
+
+Operational record:
+
+- "I can save that. What is the one timing or placement detail that still needs to be
+  decided?"
+
+Update record:
+
+- "Before I change it, what feels newly true now, and what should stay intact?"
 
 ## Question design rules
 
-- Prefer one clean question over a stacked sentence with multiple asks.
-- For straightforward logistical entities such as tasks, calendar events, work blocks,
-  timeboxes, and task runs, use the fast path: confirm what is already clear and ask
-  for only the one missing operational detail.
-- When you need two details, ask for the more meaning-bearing one first.
-- If the user sounds uncertain, ask for an example before an abstraction.
-- If the user sounds clear and decisive, confirm the working formulation and move to the
-  one missing structural detail.
-- A good next question usually clarifies one of these:
-  what this is,
-  why it matters,
-  where it belongs,
-  what success looks like,
-  when it should happen,
-  or what should stay linked.
-- Before the final save question, it is often better to offer a tentative formulation
-  than to ask for a raw title. Example shape:
-  "This sounds like a project about repairing trust with Lea, not just a loose note.
-  Does that fit, and if so what outcome would tell you it is moving?"
-- Avoid dead-form prompts like "What should this be called?" when the user is still
-  figuring out what the thing is. Name first, then ask for correction.
+- Let each question have one job:
+  clarify the shape,
+  clarify the purpose,
+  clarify the placement,
+  clarify the success condition,
+  clarify the timing,
+  or clarify the links.
+- Do not over-warm or over-therapize logistical records. For those flows, one brief
+  confirming sentence plus one question is usually enough.
+- Ask the more meaning-bearing question before the more administrative one.
+- If the user is uncertain, ask for a recent example before asking for an abstraction.
+- If the user is clear and decisive, confirm the working formulation and move directly
+  to the one missing structural detail.
+- Avoid dead-form prompts such as "What should this be called?" when the user is still
+  figuring out what the thing is.
+- Before the final save question, it is often better to offer a candidate formulation
+  than to ask for raw wording from scratch.
+- When useful, say what you think the record is becoming before asking the next
+  question. That helps the user correct the shape early.
+
+## Ready-to-save check
+
+Before saving, make sure you can answer all of these in plain language:
+
+- What is this record actually for?
+- Why is this the right Forge entity type?
+- What would make the record recognizable later?
+- What one structural detail is still worth asking for, if any?
+
+If the answer to the last question is "none", save it instead of prolonging intake.
 
 ## Update loop
 
 Use this when the user is updating an existing record rather than creating a new one.
 
 1. Ask what feels newly true, newly urgent, or newly clear.
-2. Ask what should stay intact so the record does not lose its core meaning.
-3. Ask for the concrete trigger for the update if it matters.
+2. Ask what should stay true so the record keeps its core meaning.
+3. Ask what prompted the update now if that changes the shape of the record.
 4. Then ask only for the missing structural detail required by the change.
 
 ## Goal
@@ -75,9 +121,15 @@ Arc:
 
 1. Ask what direction or outcome the user wants to keep in view.
 2. Ask why it matters now.
-3. Distinguish the goal from a project or task.
+3. Distinguish the goal from a project or task if needed.
 4. Clarify horizon and status only after the meaning is clear.
 
+Helpful follow-up lanes:
+
+- why this direction matters now
+- what would count as movement without turning it into a task list
+- whether it is a quarter, year, or life direction
+
 Ready to save when:
 
 - the goal has a stable name
@@ -86,7 +138,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What direction are you trying to hold onto here, in a way you would want future-you to keep seeing?"
+- "What direction here feels important enough that you want to keep it in view?"
 
 ## Project
 
@@ -94,20 +146,27 @@ Aim: turn an intention into a bounded workstream with a clear outcome.
 
 Arc:
 
-1. Ask what this piece of work should be called.
-2. Ask what outcome would make the project feel real or complete for now.
+1. Ask what this piece of work is trying to make true.
+2. Ask what outcome would make it feel real or complete for now.
 3. Ask which goal it belongs under.
-4. Clarify status, owner, and notes only after the scope is clear.
+4. Land on a working name once the scope is clear.
+5. Clarify status, owner, and notes only after the scope is clear.
+
+Helpful follow-up lanes:
+
+- what concrete outcome would make this project complete enough
+- what belongs inside the boundary and what does not
+- which goal gives the project meaning
 
 Ready to save when:
 
 - the project has a clear name
 - the outcome is concrete enough to recognize later
-- its parent goal is known or intentionally absent pending follow-up
+- its parent goal is known or intentionally absent
 
 Preferred opening question:
 
-- "If this becomes a real project in Forge, what outcome would make it feel genuinely underway or complete?"
+- "If this became a real project, what would you be trying to make true?"
 
 ## Strategy
 
@@ -115,17 +174,24 @@ Aim: turn a vague plan into a deliberate sequence toward a real end state.
 
 Arc:
 
-1. Ask what end state the strategy is trying to land.
+1. Ask what future state the strategy is trying to make real.
 2. Ask which goals or projects are the true targets.
-3. Ask what the major steps or nodes are.
+3. Ask what the major steps or phases are.
 4. Ask about order, dependencies, and anything that must not be skipped.
-5. Clarify linked entities or ownership once the sequence itself makes sense.
+5. Clarify links or ownership once the sequence itself makes sense.
+
+Helpful follow-up lanes:
+
+- what the end state looks like when it is real
+- what the major phases are
+- which steps must happen before others
+- what is in scope versus out of scope
 
 Ready to save when:
 
 - the strategy has a stable name
 - the end state is concrete enough to test
-- the directed sequence is sketched clearly enough to build the graph
+- the directed sequence is sketched clearly enough to build
 
 Preferred opening question:
 
@@ -139,7 +205,14 @@ Arc:
 
 1. Ask what the next concrete action is.
 2. Ask where it belongs: project, goal, both, or standalone.
-3. Ask what would make it easier to do: due date, priority, owner, or brief context.
+3. Ask what would make it easier to do: due date, priority, owner, or one line of
+   context.
+
+Helpful follow-up lanes:
+
+- turn vague intent into an actionable verb
+- identify parent project or goal
+- capture the one timing or priority detail that will actually help
 
 Ready to save when:
 
@@ -153,14 +226,22 @@ Preferred opening question:
 
 ## Habit
 
-Aim: define the recurring behavior and the cadence in a way that makes later check-ins unambiguous.
+Aim: define the recurring behavior and the cadence in a way that makes later check-ins
+unambiguous.
 
 Arc:
 
-1. Ask what the recurring behavior is in plain language.
+1. Ask what recurring move the user is trying to strengthen or loosen.
 2. Ask whether doing it is aligned or a slip.
-3. Ask about cadence and what counts as success in practice.
-4. Ask about links to goals, tasks, or Psyche entities only if that would help later review.
+3. Ask what honest success or failure looks like in practice.
+4. Ask about cadence and links only after the behavior is concrete.
+
+Helpful follow-up lanes:
+
+- what the recurring move looks like on an ordinary day
+- whether the habit is `positive` or `negative`
+- what counts as an honest check-in
+- what cadence is realistic and meaningful
 
 Ready to save when:
 
@@ -170,24 +251,31 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What is the recurring behavior you want Forge to keep track of?"
+- "What recurring move are you trying to strengthen or loosen?"
 
 ## Note
 
-Aim: preserve the useful context and link it to the right places without turning the note into a dumping ground.
+Aim: preserve the useful context and link it to the right places without turning the
+note into a dumping ground.
 
 Arc:
 
 1. Ask what the note needs to preserve.
 2. Ask what entities it should stay attached to.
 3. Ask whether it should be durable or temporary.
-4. Ask about tags or author only if they help retrieval or handoff.
+4. Ask about tags or author only if they will help retrieval or handoff.
+
+Helpful follow-up lanes:
+
+- what the note is for later
+- what should stay linked
+- whether it is durable or should expire
 
 Ready to save when:
 
 - the note body captures the important point
 - the links are clear
-- durability versus ephemeral memory is clear when relevant
+- durability is clear when relevant
 
 Preferred opening question:
 
@@ -195,7 +283,8 @@ Preferred opening question:
 
 ## Insight
 
-Aim: capture one grounded observation or recommendation clearly enough that it remains useful later.
+Aim: capture one grounded observation or recommendation clearly enough that it stays
+useful later.
 
 Arc:
 
@@ -203,6 +292,12 @@ Arc:
 2. Ask what entity or timeframe it belongs to, if any.
 3. Ask what recommendation, caution, or invitation should remain explicit.
 
+Helpful follow-up lanes:
+
+- what the core observation is
+- who or what it belongs to
+- what the practical recommendation is
+
 Ready to save when:
 
 - the observation has a stable title or phrase
@@ -215,7 +310,8 @@ Preferred opening question:
 
 ## Calendar Event
 
-Aim: make the event legible as a real commitment in time, with the right timezone and links.
+Aim: make the event legible as a real commitment in time, with the right timezone and
+links.
 
 Arc:
 
@@ -224,6 +320,12 @@ Arc:
 3. Ask where it belongs or what it supports.
 4. Ask whether it should stay Forge-only only if that choice matters.
 
+Helpful follow-up lanes:
+
+- exact start and end time
+- local timezone if there is ambiguity
+- linked goal, project, task, or note
+
 Ready to save when:
 
 - the title is clear
@@ -245,6 +347,13 @@ Arc:
 3. Ask whether it allows or blocks work.
 4. Ask whether it has a start or end date.
 
+Helpful follow-up lanes:
+
+- what the block is for
+- recurrence timing
+- blocking state
+- optional date bounds
+
 Ready to save when:
 
 - the block has a clear purpose
@@ -263,9 +372,16 @@ Arc:
 
 1. Ask which task the slot belongs to.
 2. Ask when the slot should start and end.
-3. Ask whether this is a manual reservation, a suggestion, or a live-run alignment only if relevant.
+3. Ask whether this is a manual reservation, a suggestion, or live-run alignment only
+   if relevant.
 4. Ask about override reason only if calendar rules are being bypassed.
 
+Helpful follow-up lanes:
+
+- attached task
+- exact time window
+- scheduling context only if it changes the action
+
 Ready to save when:
 
 - the task is known
@@ -298,9 +414,140 @@ Preferred opening question:
 
 - "Which task should I start?"
 
+## Self Observation
+
+Aim: capture one observation clearly enough that it can support later reflection
+without pretending it is already a full interpretation.
+
+Arc:
+
+1. Ask what was observed.
+2. Ask when it happened or became noticeable.
+3. Ask what it may connect to: pattern, belief, value, mode, task, project, or note.
+4. Ask for tags or extra context only if that will help later review.
+
+Ready to save when:
+
+- the observation itself is clear
+- timing is clear enough
+- any useful links are captured
+
+Preferred opening question:
+
+- "What did you notice that feels worth capturing?"
+
+## Sleep Session
+
+Aim: enrich one night's record with reflective context instead of treating it like a
+generic note.
+
+Arc:
+
+1. Ask what about this night feels worth capturing.
+2. Ask whether the main point is quality, pattern, context, meaning, or links.
+3. Ask what goal, project, task, habit, or Psyche record it should stay connected to.
+4. Ask about tags only if they will help later review.
+
+Ready to update when:
+
+- the reflective takeaway is clear
+- the relevant links or tags are clear when needed
+
+Preferred opening question:
+
+- "What about this night feels worth remembering or linking?"
+
+## Workout Session
+
+Aim: enrich one workout with subjective effort, mood, meaning, or linked context.
+
+Arc:
+
+1. Ask what about the session the user wants to preserve.
+2. Ask whether the key layer is effort, mood, meaning, social context, or links.
+3. Ask what it connects to in Forge if links matter.
+4. Ask about tags only if they help later retrieval.
+
+Ready to update when:
+
+- the reflective point is clear
+- the key mood, effort, meaning, or links are clear when needed
+
+Preferred opening question:
+
+- "What about this workout feels most worth capturing?"
+
+## Preference Item Or Context
+
+Aim: understand whether the user is trying to save a preference signal, define a
+context, or inspect the learned model.
+
+Arc:
+
+1. Ask what preference question the user is trying to answer.
+2. Distinguish whether this is:
+   a direct item signal,
+   a context change,
+   or a request to inspect what Forge already knows.
+3. If the user wants live comparisons, hand off to the Preferences game UI.
+4. If the user wants a direct signal or context change, ask only for the missing domain,
+   item, or context detail.
+
+Ready to act when:
+
+- the domain is clear
+- the user intent is clear: inspect, compare, signal, or context-edit
+- the missing item or context detail is clear enough
+
+Preferred opening question:
+
+- "What preference are you trying to make clearer right now?"
+
+## Questionnaire Instrument
+
+Aim: clarify whether the user is authoring a reusable questionnaire and what the
+instrument is for.
+
+Arc:
+
+1. Ask what the questionnaire is meant to measure or surface.
+2. Ask who it is for and when it should be used.
+3. Ask what style of questions it needs before getting into item wording.
+4. Move to draft creation once the purpose is clear.
+
+Ready to act when:
+
+- the purpose is clear
+- the audience or use context is clear
+- the instrument is distinct enough to draft
+
+Preferred opening question:
+
+- "What is this questionnaire meant to help surface or measure?"
+
+## Questionnaire Run
+
+Aim: clarify whether the user wants to start, continue, or complete one answer session.
+
+Arc:
+
+1. Ask which questionnaire run this is about.
+2. Ask whether the user wants to start, continue, review, or complete it.
+3. If answering is still in progress, ask only for the next answer or note that matters.
+
+Ready to act when:
+
+- the questionnaire is identified
+- the user intent for the run is clear
+
+Preferred opening question:
+
+- "Are you trying to start a questionnaire, continue one, or review a finished run?"
+
 ## Event Type
 
-Aim: create a reusable incident category that will actually help future reports stay consistent.
+Aim: create a reusable incident category that will actually help future reports stay
+consistent.
 
 Arc:
 
@@ -311,27 +558,27 @@ Arc:
 Ready to save when:
 
 - the label is stable
-- the category boundary is clear enough to reuse
+- the intended category is clear enough that future reports will use it consistently
 
 Preferred opening question:
 
-- "What kind of incident should this category stand for?"
+- "What kind of incident should this event type capture?"
 
 ## Emotion Definition
 
-Aim: create a reusable emotion label with enough clarity to use consistently later.
+Aim: define one reusable emotion entry clearly enough that future reports stay precise.
 
 Arc:
 
-1. Ask what emotion label the user wants to preserve.
-2. Ask what distinguishes it from nearby emotions.
-3. Ask for a broader category only if it will help later browsing or reporting.
+1. Ask what emotion this should represent.
+2. Ask what distinguishes it from nearby emotions if that matters.
+3. Ask for a short description only if later reports would benefit from it.
 
 Ready to save when:
 
-- the label is stable
-- the meaning is clear enough to reuse
+- the label is clear
+- the meaning is clear enough to reuse later
 
 Preferred opening question:
 
-- "What emotion label do you want to keep reusable in Forge?"
+- "Which emotion do you want this entry to help name more clearly?"