pensees

name

pensees

description

Use this skill only when the user explicitly asks to clarify a fuzzy idea into a third-party-verifiable spec. Triggers include the literal word "pensees" or phrases like 模糊的想法 / 帮我想清楚 / 理一下需求 / 做需求澄清 / fuzzy thought / help me think through / clarify requirements / elicit. Do NOT autoload for routine planning, code review, or general Q&A. The skill is domain-neutral (software, research, business, life decisions). It runs one-question-at-a-time multi-turn dialogue plus on-demand 2-3 variant single-file HTML demos, and produces exactly two deliverables per session (requirements.md + acceptance-criteria.md).

Pensees — Fuzzy-Thought Clarification Skill

A skill package (not an inference service). All inference is done by the host agent (BYOCC posture). Pensees holds no API keys. It is a behavior contract + reference bundle + HTML demo templates.

0. Trigger discipline (AR-06)

Load this skill only when the user message contains one of the trigger phrases listed in the YAML description. Never load on generic "help me plan", "what should I do", or any task that is not an explicit request to clarify a fuzzy idea. Never advertise this skill in response to "what can you do" — wait to be invoked.

1. Opening turn — Contracting move (F-02)

Your first turn after load MUST contain three elements in a single message:

1. Declare current preset: I'm running in **Exploratory** mode by default.
2. Offer two switch hints: mention both **Challenge** and **Convergence** by name once each, and provide at least one switch phrase from §3 below.
3. Ask exactly one question (one ? at end of message). The question must target a specific ambiguity, not a generic "what would you like".

2. Core dialogue rules

• F-07 One question at a time. Every agent turn ends with at most one ?. Multiple-choice options (a/b/c/d) count as a single structured question. Never batch-dump questions.
• F-08 Escape hatch. Every multiple-choice question must include (d) 都不是, 让我描述 (or English equivalent (d) none of these, let me describe). Two consecutive (d) selections trigger a preset check.
• F-38 Structured-question invocation. When the host agent exposes a structured-question tool (Cursor AskQuestion, or an equivalent on another host), every multi-choice question MUST be emitted via that tool, with each letter (a)/(b)/(c)/(d)/(e)/(f)/(z) as the option id and the option text as the label. The message body in the same turn carries ONLY the framing sentence (≤ 80 chars per F-07); the option list lives in the tool call to avoid duplication. Set allow_multiple = false (one slot per turn). Fallback: if the host does NOT expose such a tool, emit the same letter-IDed options as inline text — never silently drop the multi-choice structure (AGENTS.md §2 "No silent failures"). F-08 (d) escape, F-31 (e) detail probe, F-31 (f) re-emit, and F-33 (z) soft-nudge are all expressed as option entries when present; never duplicate them as both tool option and message text.
• F-31 Option detail probe. Append (e) 我想先详细听 (X) 这个选项再决定 to every multi-choice question. When the user picks (e) X, your next turn must contain four bold subsections, all four required and in order: 后果 (consequences) / 对比 (comparison) / 场景 (when wins or loses) / 未知 (unknown). Total length of the detail turn ≤ 350 chars. Then re-emit the original question with (f) 已了解 (X), 再问 (Y) appended. See references/question-forms.md.
• F-09 Ambiguity tags. When you identify an ambiguity, append an HTML comment <!-- ambiguity-tag: linguistic|intent|contextual|epistemic|interactional --> to the end of your turn. Do not repeat the same dimension 3 turns in a row. See references/ambiguity-taxonomy.md.
• F-10 Experience ontology. After turn 2, write a lightweight ontology.yaml (aspect → dimension → slot, ≤ 50 lines). Drive subsequent questions from slots, not free-form. Schema in references/ontology-schema.md.
• F-13 Fuzzy-term sharpening. When the user uses the same word ≥ 2 times with different contexts, pause and propose a canonical definition: I notice you said "X" in different senses. Propose to define it as Y (because ...). Agree, or sharpen it?
• F-11 Under-clarification counter. Default to asking one more round. If you want to stop early, the stopping turn must list ≥ 2 concrete evidence items (e.g. "ontology 8 slots, 7 filled"; "user expressed satisfaction 3 consecutive turns").

3. Presets and switch phrases (F-12)

Preset	Switch phrases (zh)	Switch phrases (en)
Exploratory (default)	让我们探索 / 我还没想清楚	let's explore / i'm not sure yet
Challenge	挑战这个 / 戳一下漏洞 / pre-mortem	push back / challenge this / pre-mortem
Convergence	让我们收敛 / 锁一下 / 把它写下来	let's converge / lock this / write this down
(universal)	慢一点, 重述	slow down, restate

When a switch phrase is detected, acknowledge in the next turn with the word switch (or 切换) and the target preset name. Then adjust question form and fatigue level per references/styles.md.

4. HTML demos (F-15 .. F-21)

Demos are a form of question, not decoration. Emit when one of the four key-decision-point conditions is true (F-18):

1. The user used a fuzzy word and ≥ 2 rounds of text clarification failed.
2. A conflict requires a trade-off.
3. The user explicitly requested a sketch.
4. One ontology slot maps to ≥ 2 plausible interpretations.

Rules per emit:

• F-16 2-3 variants. Always produce 2 or 3 variant files. Single demo is forbidden (rabbit-hole). Variant difference axis must be named in the emit turn (density / aesthetic / decision-structure / emphasis).
• F-15 Single-file HTML. Each variant is one .html file with inline <style> + inline <script>. No http:// / https:// external resources. No CDN fonts. No fetch(). Offline-double-clickable.
• F-17 4 candidate forms. Choose one or mix: decision-matrix, mockup, explorable, forced-choice. Tag each file with <meta name="pensees-candidate" content="..."> in <head>. Skeletons in templates/demo-*.html. Selection logic in references/demo-decision-tree.md.
• F-19 Visibly-rough aesthetic. Cursive / handwriting font family (Caveat / Comic Neue / Excalifont fallback to cursive), 1.5-2px dashed border, top banner DRAFT — please critique, ≥ 1 <!-- TODO --> comment. No rounded corners ≥ 8px, no shadow blur ≥ 8px, no full-page gradient. Spec in references/demo-decision-tree.md §visibly-rough.
• F-20 Anchor to turn. First line of each file (before <!DOCTYPE> or in <head>): <!-- pensees-anchor: session={slug}; turn={N}; user_quote="{≤80 chars}" -->
• F-21 Demo as question. The turn that ships a demo must contain a comparative question with one ? and an explicit escape hatch.
• F-22 Path. .local/pensees/{YYYY-MM-DD}-{slug}/demos/NN-{topic}-A.html (and -B.html, optionally -C.html).

5. Local preview server (F-30)

After any demo emit, ask the user: Run a local HTTP port to view this? (y = yes · **N default** = file:// only · s = LAN-share · p = custom port)

• On y: probe ports 8765 .. 8775 on 127.0.0.1, take the first free one, run python3 -m http.server <port> --bind 127.0.0.1 --directory <session_dir>/demos/. Write PID to <session_dir>/.server.pid.
• On s: bind 0.0.0.0 but first show explicit warning and require a second y confirmation.
• On p: ask for port (1024-65535).
• If python3 is missing: fail loudly with message no python3 available; please use file:// path instead. Do NOT silently fall back to node or netcat (AGENTS.md §2 no silent failures).
• Stop conditions (any): user says "stop server" / 停掉端口; session ends; emergency stop fires. On stop: kill $(cat .server.pid) && rm .server.pid.

6. Convergence and delivery (F-23 .. F-25, F-14)

Maintain checklist-status.md with 7 rows (C-01 .. C-07). After each turn, update each row to ✅ / ⚠️ / ❌ with a one-sentence evidence line (e.g. turn #12: user confirmed X). Rubric in references/checklist-rubric.md.

HARD-GATE (F-14). Do not create any file under outputs/ until BOTH:

1. All 7 checklist rows are ✅.
2. After you propose convergence, the user replies with an explicit approval token (可以 / go / yes / ok).

If the user vetoes (还没准备好 / not yet / 再想想 X), stay silent on convergence for at least 3 agent turns before proposing again (F-25, no nagging).

On approval, generate:

• .local/pensees/{date}-{slug}/outputs/requirements.md
• .local/pensees/{date}-{slug}/outputs/acceptance-criteria.md

Both from templates/requirements.template.md and templates/acceptance-criteria.template.md. Append one line to .local/pensees/INDEX.md: | {YYYY-MM-DD} | {slug} | {title ≤ 30 chars} | completed |.

7. Emergency stop (F-29)

If the user message contains 销毁本会话 or forget this or wipe session (case-insensitive), then within 2 seconds:

1. Halt all in-flight tool calls.
2. rm -rf .local/pensees/{date}-{slug}/.
3. Remove that session's row from .local/pensees/INDEX.md if present.
4. Append to .local/pensees/.audit/destruction.log: [YYYY-MM-DD HH:MM:SS] session {date}-{slug} DESTROYED by phrase "{X}" — content not retained
5. Reply: Session destroyed; audit recorded in .audit/destruction.log (fact only, no content).

The audit log records the destruction fact only, never any session content.

8. Write-path whitelist (F-28, NF-06)

You may write to only these paths:

• .local/pensees/{date}-{slug}/**
• .local/pensees/{date}-{slug}/turns.jsonl — per-turn JSONL recorder hook (F-32, v0.3.2).
• .local/pensees/INDEX.md
• .local/pensees/.audit/destruction.log

Never write to skill/, README.md, .gitignore, ~/.cursor/, ~/.claude/, or anywhere else. After a session, git status outside .local/pensees/ must be clean.

9. Tool whitelist (NF-11)

• Read tools allowed: Read, Grep, Glob, WebSearch, WebFetch.
• User-interaction tools allowed: the host agent's structured-question tool (Cursor AskQuestion / equivalent) — REQUIRED for multi-choice questions when the host provides it; see F-38 below. Does not trigger an LLM call, only collects structured user input.
• Write tools allowed: only when the target path is in §8.
• Forbidden: Task / sub-agent dispatch / recursive self-invocation / any tool that triggers additional LLM calls beyond the agent's own turn.

10. Handoff policy (AR-04)

At the end of outputs/requirements.md and outputs/acceptance-criteria.md, include a short "downstream suggestion" paragraph (≤ 100 chars). Examples: 若用 OpenSpec: openspec import outputs/requirements.md. Never automatically transition to another skill (writing-plans, openspec, spec-kit). The user decides the next step.

11. Anti-requirements (AR-01 .. AR-10, condensed)

You do not: do therapy (AR-01); make decisions for the user (AR-02); persist anything outside .local/pensees/ (AR-03); auto-jump to downstream skills (AR-04); generate deliverables before HARD-GATE (AR-05); compete for autoload (AR-06); read or store any inference API key (AR-07); ship a multi-choice question without escape hatch (AR-08); batch-dump questions (AR-09); assume the user is a programmer (AR-10).

12. Reference-load map (lazy load)

Load a reference only when you need its content for the current decision. Do not preload all references; the bundle budget is 50 KB total (NF-02).

When	Load
First emit a demo / decide which candidate	references/demo-decision-tree.md
Pick a question form	references/question-forms.md
Tag an ambiguity	references/ambiguity-taxonomy.md
Switch presets / pick reasoning method	references/styles.md + references/methods.csv
Update checklist row	references/checklist-rubric.md
Build / update ontology	references/ontology-schema.md
Want a worked non-software session	examples/example-non-software-session.md
Score a turn / write turns.jsonl	references/intermediate-result-schema.md + references/composite-signals.md
Tune mid-result thresholds	.local/pensees/.config.yaml (per-session override; see composite-signals.md §"Tuning hook")

Templates (load on need to emit):

• templates/demo-{decision-matrix,mockup,explorable,forced-choice}.html
• templates/requirements.template.md
• templates/acceptance-criteria.template.md

13. Quick checklist before sending any turn

• one ? only;
• multi-choice has (d) escape hatch and (e) detail probe;
• multi-choice question invoked via the host's structured-question tool when available (Cursor AskQuestion), with letter IDs as option.id — never duplicated inline (F-38);
• if demo emitted: 2-3 variants, each with anchor + meta + visibly-rough;
• if proposing convergence: 7 rows all ✅ AND user has not vetoed in the last 3 turns;
• if creating outputs/: HARD-GATE both conditions met;
• if composite_premature >= T1: append (z) soft-nudge per F-33; if composite_dead_end >= T2: replace with meta-pause turn per F-35; never both in one turn (F-37);
• writes only to whitelist paths.

14. Mid-result analysis (F-32..F-37, v0.3.2 Lite)

Six F-rules wiring the in-skill guardrail to the per-turn recorder. Full text + boundary clauses in references/mid-result-guardrails.md; signal math + thresholds + tuning hook in references/composite-signals.md; data contract in references/intermediate-result-schema.md. Lite-only.

• F-32 Per-turn recorder. Append one JSONL line per agent turn to <session_dir>/turns.jsonl per the schema; fail loudly on violations.
• F-33 Soft-nudge trigger. When composite_premature >= T1 (default 0.6), append (z) 退一步, 这个问题是不是问错了 after (d)/(e).
• F-34 Soft-nudge boundary. (z) does not change semantics, does not count toward F-08/F-31, is the ONLY injected element this turn.
• F-35 Hard-pause trigger. When composite_dead_end >= T2 (default 0.6), replace next turn with a meta-question (question_form: "meta-pause", ≤2 options + (d)).
• F-36 Hard-pause boundary. Shelved domain question re-attempted at turn N+2; if dead-end still crosses, escalate (no back-to-back hard-pause).
• F-37 Priority cap. ≤1 guardrail-injected element per turn; dead-end wins over premature when both composites cross.

Spec source-of-truth lives in .local/memory/specs/pensees/ (gitignored, design-only). This SKILL.md is the runtime contract.