conversational-development

name

conversational-development

description

Epistemic-hardened conversational development skill for sea-domain-forge. Enables AI agents to collaborate with non-technical domain experts to produce technical specifications through conversation, treating conversation as a truth-production surface with full invariant enforcement. Use when: (1) gathering requirements from domain experts who don't code, (2) producing specs from conversational input that must meet SEA epistemic guarantees, (3) any conversation-to-spec path that requires confirmation gates, evidence binding, and tamper-evident claim chains. Complements conversation-to-spec by providing the epistemic safety layer.

Conversational Development

Conversation is a truth-production surface. This skill enforces epistemic invariants on all claims produced from conversation. Nothing becomes a durable specification without explicit confirmation evidence.

Core Rule

Nothing becomes a durable specification without explicit confirmation evidence. Misunderstanding, correction, hesitation, and revision are signals, not noise. Ambiguity is preserved unless explicitly resolved.

No-Technical-Debt Rule

This skill forbids placeholders of any kind:

• No TODO/FIXME/XXX/HACK/STUB markers
• No stubs, mocks-as-implementations, or empty handlers
• No raise NotImplementedError / throw new Error("not implemented")
• No pass or placeholder logic

If an issue blocks progress, present the user with explicit options and a recommendation.

Typed Input/Output

Input: Conversational Events + Declared Intent

SkillInput:
  session_id: string
  mode: "interactive" | "deterministic"   # deterministic = no wall-clock entropy
  events: ConversationEvent[]             # See references/conversation-event-schema.md
  declared_intent: string                 # "requirements-gathering" | "decision-making" | "exploration"

Output: Epistemic Envelope Artifacts

SkillOutput:
  session_envelope:                       # Wrapped in epistemic_envelope.schema.json
    epistemic_status: "observed"
    provenance_hash: "sha256:<hash>"
    produced_by: "conversation-skill"
    timestamp: string
    immutable: true
    payload:
      session_id: string
      claims: ConversationalClaim[]
      conversation_chain_hash: "sha256:<hash>"
      confirmation_gate_results: GateResult[]
  drift_signals:
    - type: "extraction_drift" | "reinterpretation_drift" | "confirmation_drift" | "scope_drift" | "concretization_drift"
      description: string
      evidence: EvidencePointer[]

Workflow

Step 1: Record Conversation Events

Every conversational turn becomes a ConversationEvent:

1. Assign sequence_number (monotonic, starting at 1)
2. Compute content_hash = sha256(canonical_utf8(content))
3. Set previous_turn_hash = previous event's content_hash (null for first)
4. Compute turn_id = sha256(session_id + str(sequence_number))
5. Classify intent_signal based on utterance analysis

Events are append-only. Never modify a recorded event.

Schema: references/conversation-event-schema.md

Step 2: Extract Claims

Transform events into ConversationalClaim objects:

1. Identify assertions from domain expert utterances
2. For each assertion, create a claim with:
   • evidence_pointers referencing the source turns (REQUIRED, non-empty)
   • specificity_level: verbatim (direct quote), paraphrased (restated), or inferred (synthesized)
   • epistemic_status: always observed at this stage
3. NEVER set epistemic_status to declared during extraction

Schema: references/conversational-claim-schema.md

Step 3: Confirmation Gate

Before any claim transitions to declared:

1. Present the claim to the domain expert for explicit confirmation
2. Record a confirmation turn (intent_signal: "confirmation")
3. Populate confirmation_evidence on the claim
4. Evaluate the confirmation gate (8 checks)
5. Only if gate returns allowed: true, set epistemic_status: "declared"

Inferred claims require enhanced confirmation — the domain expert must confirm the specific inference, not just affirm a general summary.

Gate spec: references/confirmation-gate-spec.md

Step 4: Wrap in Epistemic Envelope

All durable artifacts use the epistemic envelope schema:

{
  "epistemic_status": "observed",
  "provenance_hash": "sha256:<hash of canonical(payload)>",
  "produced_by": "conversation-skill",
  "timestamp": "<ISO 8601>",
  "immutable": true,
  "payload": { "session_id": "...", "claims": [...] }
}

Claims with epistemic_status: "declared" produce envelopes with epistemic_status: "declared".

Step 5: Persist Through Write-Policy Gate

All filesystem writes route through the existing WritePolicyGate:

gate = WritePolicyGate(repo_root=Path(repo_root))
gate.ensure_write_allowed(
    path=output_path,
    operation="conversation-skill-write",
    actor="conversation-skill",
)

Conversation artifacts write to: artifacts/conversations/<session_id>/

Conversation artifacts NEVER write to: declared reality zones (docs/specs/, invariants/, config/governance/, ontologies/).

Step 6: Delegate to Spec Authoring (Optional)

When confirmed claims are ready for spec creation:

1. Verify ALL claims have epistemic_status: "declared"
2. Verify ALL claims have passing confirmation gate results
3. Package claims + gate results into the delegation payload
4. Invoke conversation-to-spec skill
5. The resulting spec envelope carries produced_by: "conversation-skill" provenance

Spec authoring MUST NOT accept conversation-originated claims without gate results.

Failure Classes

ID	Name	Severity
FC-CONV-001	Assumption drift	High
FC-CONV-002	Premature concretization	High
FC-CONV-003	Silent reinterpretation	High
FC-CONV-004	Confirmation theater	Critical
FC-CONV-005	Ungated spec injection	Critical

Reference: references/failure-classes.md

Handling Corrections and Retractions

When a domain expert corrects a prior statement:

1. Record the correction turn (intent_signal: "correction")
2. Create a new claim with supersedes pointing to the corrected claim
3. Transition the old claim to epistemic_status: "retracted"
4. The new claim starts as observed and must pass its own confirmation gate

When a domain expert retracts a statement:

1. Record the retraction turn (intent_signal: "retraction")
2. Transition the referenced claim to epistemic_status: "retracted"
3. Retraction is recorded in the session's gate results audit trail

Handling Hesitation

When a domain expert expresses uncertainty (intent_signal: "hesitation"):

1. Record the hesitation turn
2. Any claims derived from hesitant turns MUST have specificity_level: "inferred"
3. Do NOT attempt to concretize the hesitation into a firm requirement
4. Explicitly surface the ambiguity for resolution

Deterministic Mode (Default)

In deterministic mode:

• turn_id = sha256(session_id + str(sequence_number)) — no UUID
• timestamp = epoch + sequence_number seconds — no wall clock
• session_id = sha256(canonical(initial session parameters)) — content-addressed
• Gate results are deterministic: same inputs → same outputs

Integration with Other Plugin Skills

Skill	Integration Point	Boundary
conversation-to-spec	UX flow (Phases 1–6)	This skill provides epistemic enforcement; that skill provides UX flow
cognitive-artifacts	Visualization during conversation	Artifacts are observed until confirmed
doc-coauthoring	Documentation from confirmed claims	Receives only declared claims

Extensibility

Sub-skills may extend this skill by:

• Adding new claim_type values (without changing gate logic)
• Adding new intent_signal values (without changing evidence requirements)
• Adding new extraction strategies (without changing confirmation requirements)

Sub-skills MUST NOT:

• Bypass the confirmation gate
• Produce declared claims without evidence
• Write outside existing WritePolicyGate enforcement
• Remove or weaken evidence pointer requirements