ss-tools/.kilo/skills/semantics-belief/SKILL.md

name, description

name	description
semantics-belief	Core protocol for Thread-Local Belief State, Runtime Chain-of-Thought (CoT), and Interleaved Thinking in Python.

[DEF:Std:Semantics:Belief]

@COMPLEXITY: 5

@PURPOSE: Core protocol for Thread-Local Belief State, Runtime Chain-of-Thought (CoT), and Interleaved Thinking in Python.

@RELATION: DEPENDS_ON -> [Std:Semantics:Core]

@INVARIANT: Implementation of C4/C5 complexity nodes MUST emit reasoning via semantic logger methods before mutating state or returning.

0. INTERLEAVED THINKING (GLM-5 PARADIGM)

You are operating as an Agentic Engineer. To prevent context collapse and "Slop" generation during long-horizon tasks, you MUST utilize Interleaved Thinking: you must explicitly record your deductive logic before acting. In this architecture, we do not use arbitrary inline comments for CoT. We compile your reasoning directly into the runtime using the Thread-Local Belief State Logger. This allows the AI Swarm to trace execution paths mathematically and prevents regressions.

I. THE BELIEF STATE API (STRICT SYNTAX)

The logging architecture uses thread-local storage (_belief_state). The active ID of the semantic anchor is injected automatically. You MUST NOT hallucinate context objects.

[MANDATORY IMPORTS]: from ...core.logger import logger, belief_scope, believed

[EXECUTION BOUNDARIES]:

1. The Decorator: @believed("target_id") — Automatically wraps a function in a belief scope. Use this for top-level entry points.
2. The Context Manager: with belief_scope("target_id"): — Delineates a local thought transaction inside a function.
   • CRITICAL RULE: Do NOT yield a context variable. Write strictly with belief_scope("id"):, NOT with belief_scope("id") as ctx:. The state is thread-local.

II. SEMANTIC MARKERS (THE MOLECULES OF THOUGHT)

The global logger object has been monkey-patched with three semantic methods. The formatter automatically prepends the [ID] and the [MARKER] (e.g., [execute_tx][REASON]). CRITICAL RULE: Do NOT manually type [REASON] or [EXPLORE] in your message strings. Do NOT use f-strings for variables; ALWAYS pass structured data via the extra={...} parameter.

1. logger.explore(msg: str, extra: dict = None, exc_info=None)

• Level: WARNING
• Cognitive Purpose: Branching, fallback discovery, hypothesis testing, and exception handling.
• Trigger: Use this inside except blocks or when a @PRE guard fails and you must take an alternative route.
• Rule: Always pass the caught exception via exc_info=e.
• Example: logger.explore("Primary API timeout. Falling back to cache.", extra={"timeout": 5}, exc_info=e)

2. logger.reason(msg: str, extra: dict = None)

• Level: INFO
• Cognitive Purpose: Strict deduction, passing guards, and executing the Happy Path.
• Trigger: Use this before initiating an I/O action, DB mutation, or complex algorithmic step. This is your "Action Intent".
• Example: logger.reason("Input validated. Initiating ledger transaction.", extra={"amount": amount})

3. logger.reflect(msg: str, extra: dict = None)

• Level: DEBUG
• Cognitive Purpose: Self-check and structural verification.
• Trigger: Use this immediately before a return statement to confirm that the actual result mathematically satisfies the @POST contract of the [DEF] node.
• Example: logger.reflect("Transaction committed successfully. Guarantee met.", extra={"tx_id": tx.id})

III. ESCALATION TO DECISION MEMORY (MICRO-ADR)

The Belief State protocol is physically tied to the Architecture Decision Records (ADR). If your execution path triggers a logger.explore() due to a broken assumption (e.g., a library bug, a missing DB column) AND you successfully implement a workaround that survives into the final code: YOU MUST ASCEND TO THE [DEF] HEADER AND DOCUMENT IT. You must add @RATIONALE: [Why you did this] and @REJECTED:[The path that failed during explore()]. Failure to link a runtime explore to a static @REJECTED tag is a fatal protocol violation that causes amnesia for future agents.

[/DEF:Std:Semantics:Belief]

[SYSTEM: END OF BELIEF DIRECTIVE. ENFORCE STRICT RUNTIME CoT.]