forge-openclaw-plugin 0.2.25 → 0.2.27

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -7,8 +7,14 @@ Forge correctly, and gather only the structure that still matters.
 
 ## Core stance
 
+- 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.
 - 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
@@ -20,6 +26,10 @@ Forge correctly, and gather only the structure that still matters.
   brief reflection -> one orienting question.
 - Another good shorthand for the same rhythm is:
   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.
+- 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,
   timeboxes, and task runs, use a fast path:
   one brief confirming sentence -> one operational question.
@@ -27,14 +37,24 @@ Forge correctly, and gather only the structure that still matters.
   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.
+- 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
 
@@ -71,6 +91,123 @@ 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.
+
+When the user is still searching:
+
+- reflect the stake in one sentence, then ask for the smallest concrete example or the
+  desired outcome
+
+When the user already knows what they mean:
+
+- offer the working formulation, then ask only for the last missing placement, timing,
+  or ownership detail
+
+When the record carries emotion but is not Psyche:
+
+- reflect what the user is trying to hold onto, repair, or not lose, then ask one
+  orienting question
+
+When the user is updating an existing record:
+
+- ask what is changing, what should remain true, and what prompted the change now only
+  if those answers would alter the record shape
+
+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.
+
+## 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
+
 ## Question design rules
 
 - Let each question have one job:
@@ -82,16 +219,36 @@ Update record:
   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.
 - 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.
+- 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
   question. That helps the user correct the shape early.
+- For reusable vocabulary or taxonomy records such as `tag`, `event_type`,
+  `emotion_definition`, `preference_catalog`, and `preference_context`, ask what
+  distinction the label should help the user notice, sort, or retrieve later before
+  you ask about naming or aliases.
+- For emotionally meaningful vocabulary records such as `event_type`,
+  `emotion_definition`, and many `self_observation` entries, start from the lived
+  moment or felt meaning before you move to reuse or retrieval language.
+- 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.
 
 ## Ready-to-save check
 
@@ -104,6 +261,14 @@ Before saving, make sure you can answer all of these in plain language:
 
 If the answer to the last question is "none", save it instead of prolonging intake.
 
+Before the final write, it is usually worth asking one light confirmation such as:
+
+- "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.
@@ -113,6 +278,9 @@ Use this when the user is updating an existing record rather than creating a new
 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.
 
+If the current title or shape may no longer fit, offer one revised formulation yourself
+before asking the user to rewrite it from scratch.
+
 ## Goal
 
 Aim: clarify the direction and why it matters, not just produce a title.
@@ -120,9 +288,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:
 
@@ -138,7 +307,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
 
@@ -147,10 +316,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:
 
@@ -166,7 +336,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
 
@@ -175,10 +345,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:
 
@@ -195,7 +366,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
 
@@ -222,7 +393,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
 
@@ -251,7 +422,35 @@ 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
+
+Aim: create a label that helps future retrieval or grouping, not just another vague
+bucket.
+
+Arc:
+
+1. Ask what the tag should help the user notice, group, or find later.
+2. Ask what kinds of records should belong under it.
+3. Offer a concise label if the meaning is clearer than the wording.
+4. Ask about color, kind, or parent grouping only if that changes how it will be used.
+
+Helpful follow-up lanes:
+
+- what the tag is for later
+- what should count as inside versus outside the label
+- whether the user already has nearby tags that this should stay distinct from
+
+Ready to save when:
+
+- the tag has a stable label
+- the grouping meaning is clear enough to reuse later
+- any important distinction from nearby tags is clear
+
+Preferred opening question:
+
+- "What do you want this tag to help you notice or find again later?"
 
 ## Note
 
@@ -270,6 +469,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:
 
@@ -279,7 +480,36 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What feels important to preserve from this?"
+- "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
 
@@ -422,9 +652,13 @@ 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.
 
 Ready to save when:
 
@@ -434,7 +668,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
 
@@ -455,7 +689,7 @@ Ready to update when:
 
 Preferred opening question:
 
-- "What about this night feels worth remembering or linking?"
+- "What about this night feels important enough to remember or connect?"
 
 ## Workout Session
 
@@ -475,33 +709,152 @@ Ready to update when:
 
 Preferred opening question:
 
-- "What about this workout feels most worth capturing?"
+- "What about this workout feels most worth remembering or connecting?"
 
-## Preference Item Or Context
+## Calendar Connection
 
-Aim: understand whether the user is trying to save a preference signal, define a
-context, or inspect the learned model.
+Aim: connect the right provider deliberately without turning setup into a credential
+dump.
 
 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.
+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 Catalog
+
+Aim: define a useful comparison pool, not just a list with no decision purpose.
+
+Arc:
+
+1. Ask what preference question this catalog is meant to support.
+2. Ask what domain or concept area it belongs to.
+3. Ask what kinds of items should be included or excluded.
+4. Offer a working catalog name once the purpose is clear.
+
+Helpful follow-up lanes:
+
+- what decision or taste question this catalog should help answer
+- what belongs in scope
+- what would make the catalog immediately useful instead of bloated
+
+Ready to save when:
+
+- the catalog has a stable purpose
 - the domain is clear
-- the user intent is clear: inspect, compare, signal, or context-edit
-- the missing item or context detail is clear enough
+- the boundary of what belongs inside is clear enough
 
 Preferred opening question:
 
-- "What preference are you trying to make clearer right now?"
+- "What decision or taste question should this catalog help with?"
+
+## Preference Catalog Item
+
+Aim: add one candidate in a way that will make later comparisons feel clear and fair.
+
+Arc:
+
+1. Ask what makes this item worth including in the catalog.
+2. Ask what catalog or domain it belongs to if that is still unclear.
+3. Ask for a short clarifying description only if the label would be ambiguous later.
+4. Ask about aliases or tags only if they help retrieval.
+
+Helpful follow-up lanes:
+
+- why this item belongs in the comparison pool
+- what would distinguish it from nearby items
+- whether the label alone will be clear later
+
+Ready to save when:
+
+- the item label is clear
+- the parent catalog is clear
+- there is enough context to recognize it later if the label is ambiguous
+
+Preferred opening question:
+
+- "What makes this option meaningfully worth comparing?"
+
+## Preference Context
+
+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 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:
+
+- what decisions this context should shape
+- what belongs inside versus outside the mode
+- whether it should be default or explicitly separate
+
+Ready to save when:
+
+- the context has a stable purpose
+- its boundary is clear enough to use consistently
+- any default or sharing choice that matters is clear
+
+Preferred opening question:
+
+- "In what situation should Forge treat your preferences differently here?"
+
+## Preference Item
+
+Aim: save one concrete preference candidate or signal without losing the context that
+makes it meaningful.
+
+Arc:
+
+1. Ask what preference or taste question this item belongs to.
+2. Ask what domain or context it should live in.
+3. Ask whether the user is trying to save it as a comparison candidate or as a direct
+   signal such as favorite, veto, or compare-later.
+4. Ask what makes this item distinct enough to compare usefully only if it is still a
+   comparison candidate.
+5. If the user is really trying to send a direct signal, ask only for the missing
+   detail and then act.
+
+Helpful follow-up lanes:
+
+- what domain this belongs to
+- what context makes the preference meaningful
+- whether this is a signal or a comparison candidate
+- what distinguishes the item from nearby options
+
+Ready to act when:
+
+- the item is clear
+- the domain or profile context is clear enough
+- any needed distinguishing detail is captured
+
+Preferred opening question:
+
+- "What preference are you trying to make clearer by saving this item?"
 
 ## Questionnaire Instrument
 
@@ -512,8 +865,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 style of questions it needs 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:
 
@@ -523,7 +878,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
 
@@ -542,7 +897,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
 
@@ -551,9 +906,14 @@ consistent.
 
 Arc:
 
-1. Ask what category the label should capture.
+1. Ask what kind of moment or incident this label should capture in lived terms.
 2. Ask how narrow or broad it should be.
-3. Ask for a short description only if the label could be ambiguous later.
+3. Ask what would count as inside versus outside the category if that boundary is
+   still fuzzy.
+4. Ask for a short description only if the label could be ambiguous later.
+
+If the user already offered a candidate label, keep the wording provisional and ask
+what kinds of moments belong inside it before you ask whether the label is right.
 
 Ready to save when:
 
@@ -562,7 +922,7 @@ Ready to save when:
 
 Preferred opening question:
 
-- "What kind of incident should this event type capture?"
+- "What kind of moment keeps happening that you want future reports to name the same way each time?"
 
 ## Emotion Definition
 
@@ -570,10 +930,15 @@ Aim: define one reusable emotion entry clearly enough that future reports stay p
 
 Arc:
 
-1. Ask what emotion this should represent.
+1. Ask what this feeling is like in lived terms when the user says it.
 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
@@ -581,4 +946,4 @@ Ready to save when:
 
 Preferred opening question:
 
-- "Which emotion do you want this entry to help name more clearly?"
+- "When this feeling is present, what tells you it is this feeling and not a nearby one?"