self-improving-conversation

Captures dialogue learnings, tone mismatches, escalation failures, and conversation quality issues. Logs redacted summaries to .learnings/. Optional project-scoped hooks use a narrow matcher. Promote to prompt files or extract skills only after explicit human review of a diff. Use when: (1) A user expresses frustration or confusion, (2) Tone mismatch is detected, (3) Context is lost mid-conversation, (4) Agent hallucinates, (5) User requests escalation, (6) Conversation is abandoned or rephrased repeatedly, (7) A missing conversational capability is identified.

Self-Improving Conversation Skill

Log dialogue learnings, tone issues, and conversation failures to markdown files for continuous improvement. Conversational agents can later process these into playbooks. Important patterns may be promoted to project memory after explicit human review of a diff. Optional hooks are reminder-only and project-scoped.

First-Use Initialisation

Before logging anything, ensure the .learnings/ directory and files exist in the project or workspace root. If any are missing, create them:

bash

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nTone mismatches, context losses, hallucinations, and dialogue insights captured during conversations.\n\n**Categories**: tone_mismatch | misunderstanding | escalation_failure | context_loss | sentiment_drift | hallucination\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/DIALOGUE_ISSUES.md ] || printf "# Dialogue Issues Log\n\nConversation failures, misunderstandings, tone mismatches, and escalation problems.\n\n---\n" > .learnings/DIALOGUE_ISSUES.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nConversational capabilities requested by users or identified through dialogue analysis.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

Never overwrite existing files. This is a no-op if .learnings/ is already initialised.

Do not log personally identifiable information, auth tokens, or private user data unless the user explicitly asks for that level of detail. Prefer short summaries or redacted excerpts over raw conversation transcripts.

If you want automatic reminders or setup assistance, use the opt-in hook workflow described in Hook Integration.

Quick Reference

Situation	Action
User says "That's not what I meant"	Log to .learnings/DIALOGUE_ISSUES.md with misunderstanding
Formal response to casual user	Log to .learnings/LEARNINGS.md with category tone_mismatch
Lost thread in multi-turn dialogue	Log to .learnings/LEARNINGS.md with category context_loss
Agent states incorrect facts	Log to .learnings/LEARNINGS.md with category hallucination
User asks for human agent	Log to .learnings/DIALOGUE_ISSUES.md with escalation_failure
User sentiment drops mid-conversation	Log to .learnings/LEARNINGS.md with category sentiment_drift
User requests missing capability	Log to .learnings/FEATURE_REQUESTS.md
User abandons conversation	Log to .learnings/DIALOGUE_ISSUES.md with abandonment
Simplify/Harden recurring patterns	Log/update .learnings/LEARNINGS.md with Source: simplify-and-harden and a stable Pattern-Key
Similar to existing entry	Link with **See Also**, consider priority bump
Conversation pattern is proven	Propose a reviewed diff for SOUL.md, AGENTS.md, or TOOLS.md; apply only after explicit approval

OpenClaw Setup (Recommended)

OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading.

Installation

Via ClawdHub (recommended):

bash

clawdhub install self-improving-conversation

Manual:

bash

git clone https://github.com/jose-compu/self-improving-conversation.git ~/.openclaw/skills/self-improving-conversation

Workspace Structure

OpenClaw injects these files into every session:

text

~/.openclaw/workspace/
├── AGENTS.md          # Dialogue workflows, handoff protocols, escalation chains
├── SOUL.md            # Conversational tone, personality, empathy guidelines
├── TOOLS.md           # Integration capabilities, channel-specific gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── DIALOGUE_ISSUES.md
    └── FEATURE_REQUESTS.md

Create Learning Files

bash

mkdir -p ~/.openclaw/workspace/.learnings

Then create the log files (or copy from assets/):

• LEARNINGS.md — tone mismatches, context losses, hallucinations, sentiment drift
• DIALOGUE_ISSUES.md — escalation failures, misunderstandings, abandoned conversations
• FEATURE_REQUESTS.md — user-requested conversational capabilities

Promotion Targets

When learnings prove broadly applicable, promote them to workspace files:

Learning Type	Promote To	Example
Conversation patterns	SOUL.md	"Match user's formality level within 2 exchanges"
Dialogue workflows	AGENTS.md	"Offer human handoff after 3 failed intent matches"
Integration gotchas	TOOLS.md	"Slack threads lose context after 50 messages"

Optional: Enable Hook

Opt-in and project-scoped. Enabling a hook persists across future sessions; skip this unless you need reminders:

bash

cp -r hooks/openclaw ~/.openclaw/hooks/self-improving-conversation
openclaw hooks enable self-improving-conversation

See references/openclaw-integration.md for complete details.

---

Generic Setup (Other Agents)

For Claude Code, Codex, Copilot, or other agents, create .learnings/ in the project or workspace root:

bash

mkdir -p .learnings

Create the files inline using the headers shown above. Avoid reading templates from the current repo or workspace unless you explicitly trust that path.

Add reference to agent files AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md to remind yourself to log dialogue learnings. (This is an alternative to hook-based reminders.)

Self-Improving Conversation Workflow

When dialogue issues or conversation failures occur:

1. Log to .learnings/DIALOGUE_ISSUES.md, LEARNINGS.md, or FEATURE_REQUESTS.md
2. Review and promote broadly applicable patterns to:
   • CLAUDE.md - project conversation conventions
   • AGENTS.md - dialogue workflows and escalation protocols
   • .github/copilot-instructions.md - Copilot conversation context

Logging Format

Learning Entry

Append to .learnings/LEARNINGS.md:

markdown

## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: greeting | intent_detection | response_generation | handoff | follow_up | closing

### Summary
One-line description of the conversational learning

### Details
Full context: what the user said, what the agent responded, what went wrong,
what the correct response should have been

### Suggested Action
Specific conversational improvement: tone adjustment, intent mapping, escalation rule

### Metadata
- Source: conversation | user_feedback | sentiment_analysis | dialogue_review
- Related Files: path/to/dialogue_config.ext
- Tags: tag1, tag2
- See Also: LRN-20250110-001 (if related to existing entry)
- Pattern-Key: tone.formality_mismatch | context.thread_loss (optional, for recurring-pattern tracking)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

---

Dialogue Issue Entry

Append to .learnings/DIALOGUE_ISSUES.md:

markdown

## [DLG-YYYYMMDD-XXX] issue_type

**Logged**: ISO-8601 timestamp
**Priority**: high
**Status**: pending
**Area**: greeting | intent_detection | response_generation | handoff | follow_up | closing

### Summary
Brief description of the dialogue failure

### Conversation Excerpt

User: [what the user said] Agent: [what the agent responded] User: [user reaction indicating failure]

text

### Root Cause
- Misidentified intent / tone mismatch / missing context / hallucination / escalation gap

### Impact
- User frustration level: low | moderate | high | critical
- Conversation outcome: resolved_late | abandoned | escalated | unresolved

### Suggested Fix
How to handle this conversation pattern in the future

### Metadata
- Reproducible: yes | no | unknown
- Channel: web | slack | api | voice
- Related Files: path/to/intent_config.ext
- See Also: DLG-20250110-001 (if recurring)

---

Feature Request Entry

Append to .learnings/FEATURE_REQUESTS.md:

markdown

## [FEAT-YYYYMMDD-XXX] capability_name

**Logged**: ISO-8601 timestamp
**Priority**: medium
**Status**: pending
**Area**: greeting | intent_detection | response_generation | handoff | follow_up | closing

### Requested Capability
What conversational capability the user wanted

### User Context
Why they needed it, what dialogue scenario triggered it

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
How this could be built: new intent, dialogue flow, integration, playbook

### Metadata
- Frequency: first_time | recurring
- Related Features: existing_capability_name
- Channel: web | slack | api | voice

---

ID Generation

Format: TYPE-YYYYMMDD-XXX

• TYPE: LRN (learning), DLG (dialogue issue), FEAT (feature)
• YYYYMMDD: Current date
• XXX: Sequential number or random 3 chars (e.g., 001, A7B)

Examples: LRN-20250115-001, DLG-20250115-A3F, FEAT-20250115-002

Resolving Entries

When an issue is fixed, update the entry:

1. Change **Status**: pending → **Status**: resolved
2. Add resolution block after Metadata:

markdown

### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Fix Applied**: Updated intent taxonomy / added escalation rule / adjusted tone config
- **Notes**: Brief description of what was done

Other status values:

• in_progress - Actively being investigated or fixed
• wont_fix - Decided not to address (add reason in Resolution notes)
• promoted - Elevated to SOUL.md, AGENTS.md, or conversation playbook

Promoting to Project Memory

When a conversational learning is broadly applicable (not a one-off exchange), promote it to permanent project memory.

When to Promote

• Learning applies across multiple conversation flows
• Knowledge any conversational agent should know
• Prevents recurring dialogue failures
• Documents project-specific conversational conventions

Promotion Targets

Target	What Belongs There
CLAUDE.md	Project conversation conventions, tone rules, known user patterns
AGENTS.md	Dialogue workflows, escalation protocols, handoff procedures
.github/copilot-instructions.md	Conversation context and conventions for Copilot
SOUL.md	Conversational personality, empathy guidelines, tone rules (OpenClaw workspace)
TOOLS.md	Channel capabilities, integration limits, API quirks (OpenClaw workspace)

How to Promote

1. Distill the learning into a concise conversational rule or guideline
2. Prepare a minimal patch for the appropriate section in the target file (create file if needed)
3. Show a reviewed diff and apply only after explicit user approval
4. Update original entry:
   • Change **Status**: pending → **Status**: promoted
   • Add **Promoted**: SOUL.md, AGENTS.md, or target file

Promotion Examples

Learning: Agent used technical jargon with a non-technical user. Three exchanges wasted. In SOUL.md: Mirror user's vocabulary level within 2 exchanges. Avoid jargon with casual users.

Learning: User asked for human three times before agent escalated. User abandoned. In AGENTS.md: Initiate handoff after second "talk to human" request. Never require more than 2.

Recurring Pattern Detection

If logging something similar to an existing entry:

1. Search first: grep -r "keyword" .learnings/
2. Link entries: Add **See Also**: DLG-20250110-001 in Metadata
3. Bump priority if issue keeps recurring
4. Consider systemic fix: Recurring conversation issues often indicate:
   • Missing intent in taxonomy (→ update intent config)
   • Tone mismatch pattern (→ promote to SOUL.md)
   • Missing escalation path (→ promote to AGENTS.md)
   • Channel-specific limitation (→ document in TOOLS.md)

Simplify & Harden Feed

Use this workflow to ingest recurring patterns from the simplify-and-harden skill and turn them into durable conversational guidance.

Ingestion Workflow

1. Read simplify_and_harden.learning_loop.candidates from the task summary.
2. Use pattern_key as the stable dedupe key.
3. Search .learnings/LEARNINGS.md for existing entry: grep -n "Pattern-Key: <key>" .learnings/LEARNINGS.md
4. If found: increment Recurrence-Count, update Last-Seen, add See Also links.
5. If not found: create new LRN-... entry with Source: simplify-and-harden, set Pattern-Key, Recurrence-Count: 1.

Promotion Rule

Promote when: Recurrence-Count >= 3, seen across 2+ conversation flows, within 30-day window. Targets: SOUL.md (tone), AGENTS.md (escalation), TOOLS.md (channel limits). Write short prevention guidelines, not dialogue transcripts.

Periodic Review

Review .learnings/ at natural breakpoints:

When to Review

• Before handling a complex dialogue flow
• After a conversation with user frustration signals
• When working on intent taxonomy or escalation rules
• Weekly during active chatbot development

Quick Status Check

bash

# Count pending items
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

# List pending high-priority dialogue issues
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["

# Find learnings for a specific area
grep -l "Area\*\*: intent_detection" .learnings/*.md

Review Actions

• Resolve fixed dialogue issues
• Promote applicable conversational patterns
• Link related entries across flows
• Escalate recurring misunderstanding patterns

Detection Triggers

Automatically log when you notice:

Tone Mismatches (→ learning with tone_mismatch category):

• Response formality doesn't match user's style
• Overly technical language for a casual user
• Too casual for a formal/professional context
• Emoji or humor where user expects seriousness

Misunderstandings (→ dialogue issue):

• "That's not what I meant"
• "No, I was asking about..."
• "You misunderstood"
• User rephrases the same question 3+ times

Escalation Failures (→ dialogue issue with escalation_failure):

• "Can I talk to a human?"
• "Let me speak to someone real"
• "I need a real person"
• "This isn't working, transfer me"

Context Loss (→ learning with context_loss category):

• Agent asks question already answered earlier
• Agent contradicts its own prior response
• Agent loses track of multi-step request
• "I already told you that"

Sentiment Drift (→ learning with sentiment_drift category):

• User starts friendly, becomes curt
• Increasing use of caps or punctuation (!!!)
• Shorter responses indicating disengagement
• Explicit frustration markers ("ugh", "come on")

Hallucination (→ learning with hallucination category):

• Agent states business hours, policies, or data that doesn't exist
• Agent references features that aren't available
• Agent fabricates conversation history
• Agent cites non-existent documentation or sources

Feature Gaps (→ feature request):

• "Can you also handle..."
• "I wish the bot could..."
• "Why can't you understand..."
• "Do you support [language/channel]?"

Priority Guidelines

Priority	When to Use
critical	User PII exposed in conversation, security breach, data leak in dialogue
high	Repeated misunderstanding affecting core flow, escalation path broken, hallucination about critical info
medium	Tone mismatch causing friction, context loss in long conversations, sentiment drift
low	Minor phrasing improvement, edge-case intent miss, cosmetic dialogue issue

Area Tags

Use to filter learnings by conversation phase:

Area	Scope
greeting	Opening messages, welcome flows, channel detection
intent_detection	NLU, intent classification, entity extraction
response_generation	Reply composition, tone selection, content assembly
handoff	Escalation to human, agent transfer, channel switching
follow_up	Clarification loops, confirmation, next-step suggestions
closing	Farewell, satisfaction check, feedback collection

Best Practices

1. Log immediately — conversational context is lost quickly once the exchange moves on
2. Include conversation excerpts — future agents need to see the actual exchange
3. Note the user's emotional state — helps calibrate future tone adjustments
4. Record the channel — Slack, web, API, voice all have different constraints
5. Suggest concrete dialogue fixes — not just "improve response" but specific phrasing
6. Track intent taxonomy gaps — misunderstandings often mean missing intents
7. Promote tone rules aggressively — if in doubt, add to SOUL.md
8. Review before complex flows — check for known issues in similar dialogue paths

Gitignore Options

Keep learnings local (per-developer):

gitignore

.learnings/

This repo uses that default to avoid committing sensitive conversation logs by accident.

Track learnings in repo (team-wide): Only track .learnings/ after a human has reviewed entries for secrets, PII, and privileged content.

Hybrid (track templates, ignore entries):

gitignore

.learnings/*.md
!.learnings/.gitkeep

Hook Integration

Enable automatic reminders through agent hooks. This is opt-in — you must explicitly configure hooks.

Hooks persist across sessions once installed. Keep them project-scoped. Do not install user-level or global hooks. Never use an empty matcher. PostToolUse inspects command output in-process; do not log raw output, secrets, or transcripts.

Quick Setup (Claude Code / Codex)

Create .claude/settings.json in your project:

json

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "dialogue|conversation|chatbot|intent|escalat|tone|hallucin",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improving-conversation/scripts/activator.sh"
      }]
    }]
  }
}

This injects a dialogue learning evaluation reminder after matching prompts (~50-100 tokens overhead).

Advanced Setup (With Error Detection)

Add PostToolUse hook alongside activator for automated dialogue failure detection from command output. See references/hooks-setup.md for the full JSON configuration.

Available Hook Scripts

Script	Hook Type	Purpose
scripts/activator.sh	UserPromptSubmit	Reminds to evaluate dialogue learnings after tasks
scripts/error-detector.sh	PostToolUse (Bash)	Triggers on conversation error patterns

See references/hooks-setup.md for detailed configuration and troubleshooting.

Automatic Skill Extraction

Extracted skills are untrusted until a human reviews the generated SKILL.md. Do not keep or publish an extracted skill without explicit user approval.

When a conversational learning is valuable enough to become a reusable skill, extract it using the provided helper.

Skill Extraction Criteria

A learning qualifies for skill extraction when ANY of these apply:

Criterion	Description
Recurring	Has See Also links to 2+ similar dialogue issues
Verified	Status is resolved with working conversational fix
Non-obvious	Required actual dialogue analysis to discover the pattern
Broadly applicable	Not project-specific; useful across chatbot implementations
User-flagged	User says "save this as a skill" or similar

Extraction Workflow

1. Identify candidate: Dialogue learning meets extraction criteria
2. Run helper (or create manually):

   bash

   ./skills/self-improving-conversation/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improving-conversation/scripts/extract-skill.sh skill-name
   

3. Customize SKILL.md: Fill in template with conversational learning content
4. Update learning: Set status to promoted_to_skill, add Skill-Path
5. Verify: Read skill in fresh session to ensure it's self-contained

Extraction Detection Triggers

In conversation: "Save this dialogue pattern", "We keep getting this wrong", "This would help other chatbots"

In learning entries: Multiple See Also links, high priority + resolved, tone_mismatch or escalation_failure with broad applicability

Skill Quality Gates

• Pattern tested across multiple dialogue flows
• Description clear without original conversation context
• Dialogue examples anonymized (no PII)
• Follows skill naming conventions (lowercase, hyphens)

Multi-Agent Support

This skill works across different AI agents with agent-specific activation.

Claude Code

Activation: Hooks (UserPromptSubmit, PostToolUse) Setup: .claude/settings.json with hook configuration Detection: Automatic via hook scripts

Codex CLI

Activation: Hooks (same pattern as Claude Code) Setup: .codex/settings.json with hook configuration Detection: Automatic via hook scripts

GitHub Copilot

Activation: Manual (no hook support) Setup: Add to .github/copilot-instructions.md:

markdown

## Conversation Self-Improvement

After handling dialogue interactions, consider logging to `.learnings/`:
1. Tone mismatches, misunderstandings, escalation failures
2. Link related entries with See Also
3. Promote proven conversational patterns to skills

Ask in chat: "Should I log this dialogue issue?"

Detection: Manual review at session end

OpenClaw

Activation: Workspace injection + inter-agent messaging Setup: See "OpenClaw Setup" section above Detection: Via session tools and workspace files

Agent-Agnostic Guidance

Regardless of agent, apply conversation self-improvement when you:

1. Detect tone mismatch — your formality doesn't match the user's
2. Lose context — you forgot something the user already said
3. Hallucinate — you stated something factually incorrect
4. Fail to escalate — user wanted a human and didn't get one
5. Miss intent — user had to rephrase multiple times

Copilot Chat Integration

Quick prompts for Copilot users:

• "Log this dialogue issue"
• "Create a skill from this conversation pattern"
• "Check .learnings/ for related dialogue issues"

Stackability Contract (Standalone + Multi-Skill)

This skill is standalone-compatible and stackable with other self-improving skills.

Namespaced Logging (recommended for 2+ skills)

• Namespace for this skill: .learnings/conversation/
• Keep current standalone behavior if you prefer flat files.
• Optional shared index for all skills: .learnings/INDEX.md

Required Metadata

Every new entry must include:

markdown

**Skill**: conversation

Hook Arbitration (when 2+ skills are enabled)

• Use one dispatcher hook as the single entrypoint.
• Dispatcher responsibilities: route by matcher, dedupe repeated events, and rate-limit reminders.
• Suggested defaults: dedupe key = event + matcher + file + 5m_window; max 1 reminder per skill every 5 minutes.

Narrow Matcher Scope (conversation)

Only trigger this skill automatically for conversation signals such as:

• tone mismatch|intent miss|hallucination|rephrase|clarification loop
• escalation needed|user frustration|context loss
• explicit conversation intent in user prompt

Cross-Skill Precedence

When guidance conflicts, apply:

1. security
2. engineering
3. coding
4. ai
5. user-explicit domain skill
6. meta as tie-breaker

Ownership Rules

• This skill writes only to .learnings/conversation/ in stackable mode.
• It may read other skill folders for cross-linking, but should not rewrite their entries.
• Standalone mode writes to this project's .learnings/*.md log files only.
• Stackable mode writes only to the namespaced folder above and must not rewrite other skills' log entries.
• Promotion into AGENTS.md, SOUL.md, TOOLS.md, MEMORY.md, rules, hooks, or generated skills is not a logging write. Show a reviewed diff and apply only after explicit user approval.