forge-openclaw-plugin 0.2.26 → 0.2.28

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -9,8 +9,15 @@ Forge correctly, and gather only the structure that still matters.
 
 - Lead with what the user is trying to preserve, change, resolve, or make true, not
   with the entity label.
+- Start by saying what seems to matter here or what the record is becoming, then ask
+  the next useful question.
+- Whenever you can, make the direction of the intake visible before the question by
+  naming what you think the user is trying to preserve, clarify, decide, schedule, or
+  make easier.
 - Ask only for what is missing or still unclear.
 - Before every question, decide the one missing thing you are trying to clarify.
+- Ask first for the missing thing that would change the record shape, title, or next
+  action most, not just the easiest field to fill.
 - 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
@@ -24,6 +31,8 @@ Forge correctly, and gather only the structure that still matters.
   short reflection -> one orienting question.
 - When the user is vague, ask for the smallest real example, desired outcome, or stake
   before you ask for wording.
+- For strategic, reflective, or emotionally meaningful non-Psyche records, ask what
+  feels important to keep true before you ask for labels, dates, or taxonomy.
 - When the user is clear, say what the record seems to be becoming and move straight to
   the last missing structural detail.
 - For straightforward logistical entities such as tasks, calendar events, work blocks,
@@ -32,17 +41,30 @@ Forge correctly, and gather only the structure that still matters.
 - 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.
+- For action-heavy flows such as work adjustments, preference judgments, preference
+  signals, and specialized surface work in Movement, Life Force, or Workbench, first
+  ask what the user is trying to understand, change, add, update, link, or run, then
+  route to the dedicated action or surface path instead of pretending it is normal
+  CRUD.
 - Do not read schema fields out loud unless the user explicitly wants a checklist.
+- One focused question is the default. Ask two only when both questions serve the same
+  job and the user is steady enough for it.
 - 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.
+- After each substantive answer, briefly say what is becoming clearer before you ask
+  for the next missing detail.
+- Let the user feel the direction of the intake. The next question should make sense
+  because of what just became clearer, not because a hidden checklist says it is next.
 - If the user already answered the usual opening question, do not repeat the stock
   opener. Move straight to the next missing clarification.
 - After a substantive answer, briefly say what is becoming clear so the user can
   correct the direction early.
 - Once the record is clear enough to name, stop exploring broadly and ask only for the
   last missing structural detail.
+- When the record is already clear enough to save, save it instead of performing a
+  ceremonial extra question.
 
 ## Conversation arc
 
@@ -79,6 +101,28 @@ Update record:
 
 - "Before I change it, what feels newly true now, and what should stay intact?"
 
+## Turn shapes
+
+Use these as small conversation molds when you need the next turn to feel guided
+rather than mechanical.
+
+Opening turn:
+
+- briefly reflect what seems to matter here
+- ask the one question that clarifies shape, stake, or outcome most
+
+Middle turn:
+
+- say what is becoming clearer
+- name the one thing that still needs to be known
+- ask only for that
+
+Closing turn:
+
+- offer the working title, summary, or record shape in plain language
+- ask whether it feels true enough to save or needs one correction
+- if the user says yes, move to the write instead of reopening the intake
+
 ## Steering moves
 
 Use these small moves to keep the intake natural and intentional.
@@ -107,12 +151,113 @@ When you are about to save:
 
 - give one short working summary in the user's language and ask whether it feels true
   enough or needs one correction
+- if the user confirms it, stop asking and save
 
 When an adjacent record becomes visible:
 
 - name it gently and ask whether it should be linked now, saved separately later, or
   left alone for now
 
+## Question Calibration Loop
+
+Use this quick internal check before every follow-up question.
+
+1. What is the one thing still unknown?
+2. Does that unknown affect the entity shape, the wording, the placement, or the
+   operational detail?
+3. What is the smallest question that would answer that unknown?
+4. If the user already gave enough to act, stop asking and move to a short summary or
+   the write.
+
+Useful calibration heuristics:
+
+- If the unknown changes whether this is a goal, project, task, note, or Psyche
+  record, ask that first.
+- If the shape is already clear but the wording is soft, offer a candidate title or
+  formulation rather than asking the user to invent one from scratch.
+- If the wording is clear but the placement is missing, ask only for the parent,
+  timing, owner, or linked context that will make the record usable later.
+- If the user is emotionally invested but the entity is not Psyche, reflect the stake
+  once and then return to the one missing structural detail.
+- If the next question would only decorate the record and not change its usefulness,
+  skip it.
+
+## Abstract And Reusable Record Moves
+
+Use this posture for tags, event types, emotion definitions, preference contexts,
+preference catalogs, preference items, questionnaire instruments, and similar
+reusable records.
+
+- Start from the future use, decision, or repeated moment the record should clarify,
+  not from the label alone.
+- Ask what distinction this record should help the user notice, compare, sort, or
+  retrieve later.
+- For collection records, ask what they are meant to help decide before you ask what
+  belongs inside them.
+- For vocabulary records, ask what counts as inside versus outside the term before you
+  settle the wording.
+- If the user already proposes a label, keep it provisional until the boundary and
+  future use are clear.
+- Once the distinction is clear, offer a candidate label yourself and invite
+  correction instead of making the user wordsmith alone.
+
+## Opening move recipes
+
+Use these when you want the first turn to feel more guided and less form-like.
+
+Strategic record:
+
+- "This sounds like something you want to hold onto directionally, not just list.
+  What would feel important to keep true here?"
+
+Bounded-work record:
+
+- "This sounds like it wants to become a real piece of work. What outcome would make
+  it feel meaningfully real for now?"
+
+Reflective record:
+
+- "There is something here you do not want to lose. What feels most worth capturing
+  before we decide where to store it?"
+
+Reusable record:
+
+- "Before we settle the label, what future decision, comparison, or retrieval moment
+  should this help with?"
+
+Operational record:
+
+- "I can turn that into a concrete Forge action. What is the one timing, owner, or
+  placement detail that still needs to be decided?"
+
+## Name, Define, Connect
+
+Once the core record is visible, use this short checkpoint.
+
+Name:
+
+- offer a working title or label if the user has the meaning but not the wording yet
+
+Define:
+
+- ask what belongs inside this record and what would make it stop being this record
+
+Connect:
+
+- ask about links only after the record itself feels named and defined enough to stay
+  stable
+
+## Close cleanly
+
+- Once the record has a working shape, tell the user what is now clear and what one
+  detail, if any, is still worth deciding.
+- If no detail is still decision-relevant, summarize the record in plain language and
+  move to the save.
+- Prefer "what I have now is..." or "what seems clear now is..." over a cold final
+  field check.
+- If the user gives a correction, revise the working formulation once and close again
+  instead of reopening the whole intake.
+
 ## Question design rules
 
 - Let each question have one job:
@@ -124,6 +269,8 @@ When an adjacent record becomes visible:
   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.
+- The first question should usually clarify lived meaning, use, stake, or timing, not
+  ask the user to invent a title from scratch.
 - Ask the more meaning-bearing question before the more administrative one.
 - Prefer "what", "when", and "how" before "why" when the user's meaning is still
   forming. "Why" is often better after the experience or outcome is already clear.
@@ -134,6 +281,8 @@ When an adjacent record becomes visible:
   figuring out what the thing is.
 - For labels such as `tag`, `event_type`, and `emotion_definition`, do not open with a
   naming question unless the meaning is already clear and only the wording is missing.
+- For reusable records, help the user define the boundary before you settle the final
+  label.
 - 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
@@ -148,6 +297,10 @@ When an adjacent record becomes visible:
 - For collection-like records such as `preference_catalog` and
   `questionnaire_instrument`, ask what they are for before you ask what should go
   inside them.
+- After the user answers, prefer "what is becoming clearer is..." over a cold jump to
+  the next field.
+- For reusable or abstract records, it is often better to say "what this would help
+  you decide later is..." before asking for the final wording.
 
 ## Ready-to-save check
 
@@ -165,6 +318,9 @@ Before the final write, it is usually worth asking one light confirmation such a
 - "That sounds like the right shape to save. Do you want to keep it that way, or is
   there one thing you want adjusted first?"
 
+If an adjacent goal, project, task, note, value, pattern, or tag became visible, ask
+about linking only after the main record already feels named and steady.
+
 ## Update loop
 
 Use this when the user is updating an existing record rather than creating a new one.
@@ -184,9 +340,10 @@ Aim: clarify the direction and why it matters, not just produce a title.
 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 if needed.
-4. Clarify horizon and status only after the meaning is clear.
+2. Reflect back the deeper stake in plain language before moving on.
+3. Ask why it matters now.
+4. Distinguish the goal from a project or task if needed.
+5. Clarify horizon and status only after the meaning is clear.
 
 Helpful follow-up lanes:
 
@@ -202,7 +359,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What direction here feels important enough that you want to keep it in view?"
+- "What direction are you trying to keep hold of here?"
 
 ## Project
 
@@ -211,10 +368,11 @@ Aim: turn an intention into a bounded workstream with a clear outcome.
 Arc:
 
 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. Land on a working name once the scope is clear.
-5. Clarify status, owner, and notes only after the scope is clear.
+2. Reflect the emerging boundary so the user can hear what is in scope.
+3. Ask what outcome would make it feel real or complete for now.
+4. Ask which goal it belongs under.
+5. Land on a working name once the scope is clear.
+6. Clarify status, owner, and notes only after the scope is clear.
 
 Helpful follow-up lanes:
 
@@ -230,7 +388,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "If this became a real project, what would you be trying to make true?"
+- "If this became a real project, what would you be trying to make true in your life or work?"
 
 ## Strategy
 
@@ -239,10 +397,11 @@ Aim: turn a vague plan into a deliberate sequence toward a real end state.
 Arc:
 
 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 phases are.
-4. Ask about order, dependencies, and anything that must not be skipped.
-5. Clarify links or ownership once the sequence itself makes sense.
+2. Reflect the destination in plain language so the user can correct it early.
+3. Ask which goals or projects are the true targets.
+4. Ask what the major steps or phases are.
+5. Ask about order, dependencies, and anything that must not be skipped.
+6. Clarify links or ownership once the sequence itself makes sense.
 
 Helpful follow-up lanes:
 
@@ -259,7 +418,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What future state is this strategy supposed to make real?"
+- "What future state are you actually trying to arrive at with this strategy?"
 
 ## Task
 
@@ -286,7 +445,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What is the next concrete move you want to remember or do?"
+- "What is the next concrete move here?"
 
 ## Habit
 
@@ -315,7 +474,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What recurring move are you trying to strengthen or loosen?"
+- "What recurring move are you trying to strengthen or interrupt?"
 
 ## Tag
 
@@ -362,6 +521,8 @@ Helpful follow-up lanes:
 - what the note is for later
 - what should stay linked
 - whether it is durable or should expire
+- whether part of the detail belongs in a note while the cleaner structure belongs on
+  another entity
 
 Ready to save when:
 
@@ -371,7 +532,36 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What feels important enough here that you would want to be able to find it again later?"
+- "What about this feels worth preserving in a note?"
+
+## Wiki Page
+
+Aim: create a durable reference page with a clear scope instead of dumping raw notes
+into the wiki.
+
+Arc:
+
+1. Ask what topic this page should become the canonical place for.
+2. Ask whether it is a durable wiki page or supporting evidence.
+3. Ask what future lookup, decision, or collaboration this page should support.
+4. Ask about linked entities, aliases, or tags only if they will make the page more
+   navigable later.
+
+Helpful follow-up lanes:
+
+- what this page should be the home for
+- what should belong on the page versus remain linked evidence
+- who would open this page later and what they should quickly understand
+
+Ready to save when:
+
+- the page scope is clear
+- the page kind is clear enough
+- the title is stable enough to find later
+
+Preferred opening question:
+
+- "What should this page become the main reference for?"
 
 ## Insight
 
@@ -506,6 +696,33 @@ Preferred opening question:
 
 - "Which task should I start?"
 
+## Work Adjustment
+
+Aim: correct tracked minutes truthfully without pretending a live run happened.
+
+Arc:
+
+1. Ask what existing task or project the minutes belong to.
+2. Ask whether time should be added or removed.
+3. Ask what real work or correction the adjustment is meant to capture.
+4. Ask for a short audit note only if the reason would otherwise be unclear later.
+
+Helpful follow-up lanes:
+
+- what record the correction belongs to
+- whether the adjustment is positive or negative
+- what truthful reason should stay attached to the correction
+
+Ready to act when:
+
+- the target task or project is clear
+- the minute delta is clear
+- the note is clear enough when an audit trail matters
+
+Preferred opening question:
+
+- "Which task or project should this time correction belong to?"
+
 ## Self Observation
 
 Aim: capture one observation clearly enough that it can support later reflection
@@ -514,9 +731,10 @@ 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.
+2. Reflect the moment without pretending it is already a finished interpretation.
+3. Ask when it happened or became noticeable.
+4. Ask what it may connect to: pattern, belief, value, mode, task, project, or note.
+5. Ask for tags or extra context only if that will help later review.
 
 If the user already gave the moment or timing, move straight to what they noticed most
 clearly instead of re-asking when.
@@ -529,7 +747,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What did you notice that feels worth capturing?"
+- "What did you notice most clearly in that moment?"
 
 ## Sleep Session
 
@@ -572,6 +790,195 @@ Preferred opening question:
 
 - "What about this workout feels most worth remembering or connecting?"
 
+## Calendar Connection
+
+Aim: connect the right provider deliberately without turning setup into a credential
+dump.
+
+Arc:
+
+1. Ask which provider the user wants to connect and what they want Forge to do with
+   it.
+2. Ask whether the goal is read-only visibility, writable planning, or both.
+3. Ask only for the next provider-specific step that still matters, such as auth flow,
+   label, or calendar selection.
+4. Move into the actual connection flow once the setup goal is clear.
+
+Helpful follow-up lanes:
+
+- what calendar workflow the user wants to unlock
+- whether writable projection matters
+- whether the provider requires a local sign-in step instead of manual fields
+
+Ready to act when:
+
+- the provider is clear
+- the intended sync behavior is clear enough
+- the next setup step is obvious
+
+Preferred opening question:
+
+- "Which calendar provider are you trying to connect, and what do you want Forge to do with it?"
+
+## Preference Judgment
+
+Aim: capture one pairwise preference decision with the right context, not just log a
+left-versus-right click.
+
+Arc:
+
+1. Ask what comparison the user is actually trying to settle.
+2. Ask which context or domain this judgment belongs to.
+3. Ask whether the result is left, right, tie, or skip.
+4. Ask for reason tags or strength only if they will improve later interpretation.
+
+Helpful follow-up lanes:
+
+- what the comparison is really about
+- which preference context should own the signal
+- whether the choice feels decisive, weak, tied, or not ready
+
+Ready to act when:
+
+- the left and right items are clear
+- the outcome is clear
+- the relevant context or profile is clear enough
+
+Preferred opening question:
+
+- "What comparison are you actually trying to settle here?"
+
+## Preference Signal
+
+Aim: store a direct preference signal such as favorite, veto, bookmark, or
+compare-later with the context that makes it interpretable later.
+
+Arc:
+
+1. Ask what item the user wants to mark.
+2. Ask what signal they want to give it.
+3. Ask what domain or context this belongs to if that is still unclear.
+4. Ask about strength only if the user is expressing a gradient rather than a simple mark.
+
+Helpful follow-up lanes:
+
+- what item is being marked
+- whether this is a favorite, veto, bookmark, neutral, or compare-later signal
+- what context makes the signal meaningful
+
+Ready to act when:
+
+- the item is clear
+- the signal type is clear
+- the context is clear enough if it changes interpretation
+
+Preferred opening question:
+
+- "What do you want Forge to remember about this item right now?"
+
+## Movement
+
+Aim: clarify whether the user wants to understand time in place, review travel
+behavior, add or update a stay or trip, inspect one place, or link movement context to
+another Forge record before choosing the dedicated route family.
+
+Arc:
+
+1. Ask whether the user is trying to query behavior, add something manually, update an existing movement item, or link movement to another Forge entity.
+2. Ask whether the focus is a stay, a trip, a place, a timeline window, or a selected span.
+3. Ask for the time window, place, or movement item that makes the question concrete.
+4. Ask what they are trying to notice, preserve, or answer through that movement context.
+5. Route to the dedicated movement read or write path once the surface is clear.
+
+Direct action rules:
+
+- If the user is clearly talking about a missing-data gap that should become a stay or
+  trip, use a user-defined movement box.
+- Preflight with `/api/v1/movement/user-boxes/preflight` when overlap or exact timing
+  is unclear, then create the overlay with `/api/v1/movement/user-boxes`.
+- Use `kind: "stay"` when the user stayed in one place and `kind: "trip"` when they
+  traveled.
+- Use raw `PATCH /api/v1/movement/stays/:id` or `/api/v1/movement/trips/:id` only for
+  editing an already-recorded stay or trip, not for filling a missing span.
+- When the user has already given the real answer, for example "I stayed home during
+  that missing block", do not ask a broad review question again. Confirm only the
+  interval or place if that is still ambiguous, then act.
+
+Helpful follow-up lanes:
+
+- whether the user wants time-in-place, travel history, one specific stay or trip, a
+  place summary, or a link
+- what time window, place, stay, trip, or selection is in scope
+- whether the question is behavioral, such as time at home, travel frequency, or place
+  distribution, versus an edit
+- whether the edit is a missing-gap overlay versus a true recorded stay/trip patch
+
+Ready to act when:
+
+- the movement surface is clear
+- the time range, place, stay, trip, or selection is clear enough
+- the user goal is clear enough to choose the route
+
+Preferred opening question:
+
+- "Are you trying to understand where you stayed and traveled, change one stay or trip, or answer a question about your movement behavior?"
+
+## Life Force
+
+Aim: clarify whether the user wants to review current energy state, change durable
+profile assumptions, edit weekday curves, or log a real-time fatigue signal.
+
+Arc:
+
+1. Ask whether the job is overview, profile change, weekday-template change, or fatigue signaling.
+2. Ask what part of the current energy picture feels most important or inaccurate.
+3. Ask what should stay true if they are changing profile or template assumptions.
+4. Route to the dedicated life-force path once the lane is clear.
+
+Helpful follow-up lanes:
+
+- whether the user wants explanation, editing, or signaling
+- what part of the energy model feels off or useful
+- what durable assumption versus real-time state is being changed
+
+Ready to act when:
+
+- the life-force lane is clear
+- the relevant weekday, profile field, or signal is clear enough
+- the user intent is clear enough to choose overview versus mutation
+
+Preferred opening question:
+
+- "Do you want to understand the current energy picture, change how Forge models it, or log how you feel right now?"
+
+## Workbench
+
+Aim: clarify whether the user wants to inspect a flow, edit it, run it, or inspect
+results so the agent uses the dedicated workbench contract instead of vague CRUD.
+
+Arc:
+
+1. Ask whether the job is flow discovery, one flow edit, execution, run history, published output, node-level inspection, or latest-node-output lookup.
+2. Ask which flow, slug, run, or node the request is about.
+3. Ask what the user is trying to learn, repair, or publish through that flow.
+4. Route to the dedicated workbench route family once the execution lane is clear.
+
+Helpful follow-up lanes:
+
+- whether the user wants structure, execution, or results
+- what exact flow or run is in scope
+- whether they need whole-flow output or node-level detail
+
+Ready to act when:
+
+- the workbench lane is clear
+- the flow, run, or node is clear enough
+- the requested read or mutation is clear enough to choose the route
+
+Preferred opening question:
+
+- "Are you trying to inspect a flow, change it, run it, or inspect one run's outputs?"
+
 ## Preference Catalog
 
 Aim: define a useful comparison pool, not just a list with no decision purpose.
@@ -597,7 +1004,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What preference question do you want this catalog to help answer?"
+- "What decision or taste question should this catalog help with?"
 
 ## Preference Catalog Item
 
@@ -624,7 +1031,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What makes this item worth comparing in that catalog?"
+- "What makes this option meaningfully worth comparing?"
 
 ## Preference Context
 
@@ -633,9 +1040,10 @@ Aim: define a real operating mode for preferences, not a decorative label.
 Arc:
 
 1. Ask what situation or mode this context is meant to represent.
-2. Ask what should count inside that context and what should stay outside it.
-3. Ask whether it should be active, default, or kept separate from other evidence.
-4. Offer a concise name if the mode is clearer than the wording.
+2. Ask what decisions or comparisons should feel different inside that context.
+3. Ask what should count inside that context and what should stay outside it.
+4. Ask whether it should be active, default, or kept separate from other evidence.
+5. Offer a concise name if the mode is clearer than the wording.
 
 Helpful follow-up lanes:
 
@@ -651,7 +1059,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What situation or mode should this context help Forge treat differently?"
+- "In what situation should Forge treat your preferences differently here?"
 
 ## Preference Item
 
@@ -695,9 +1103,10 @@ 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 kind of questions would make it honest and useful before getting into
-   item wording.
-4. Move to draft creation once the purpose is clear.
+3. Ask what kind of honest moment or decision it should help someone answer before
+   getting into item wording.
+4. Reflect the practical use case back in plain language.
+5. Move to draft creation once the purpose is clear.
 
 Ready to act when:
 
@@ -707,7 +1116,7 @@ Ready to act when:
 
 Preferred opening question:
 
-- "What is this questionnaire meant to help surface or measure?"
+- "What would this questionnaire help someone notice or track?"
 
 ## Questionnaire Run
 
@@ -726,7 +1135,7 @@ Ready to act when:
 
 Preferred opening question:
 
-- "Are you trying to start a questionnaire, continue one, or review a finished run?"
+- "Do you want to start, continue, review, or finish a questionnaire run?"
 
 ## Event Type
 
@@ -751,7 +1160,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What kind of moment do you want this event type to help you name more consistently?"
+- "What kind of moment keeps happening that you want future reports to name the same way each time?"
 
 ## Emotion Definition
 
@@ -763,6 +1172,11 @@ Arc:
 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.
 
+Helpful follow-up lanes:
+
+- what tells the user this is that feeling and not a nearby one
+- what kind of moments this emotion name should be used for later
+
 Ready to save when:
 
 - the label is clear
@@ -770,4 +1184,4 @@ Ready to save when:
 
 Preferred opening question:
 
-- "When you say this feeling, what does it actually feel like for you?"
+- "When this feeling is present, what tells you it is this feeling and not a nearby one?"