pageel/para-workspace/deep-reasoning

Deep Reasoning Protocol (CoT Engine)

Purpose: Provide a structured, repeatable 4-phase Chain-of-Thought (CoT) reasoning protocol for high-complexity tasks, cross-cutting architectural choices, security audits, and root-cause debugging.

Trigger:

- Explicitly activated via --deep or --cot flags in workflows (e.g., /brainstorm, /sysdesign, /fix, /spec, /plan).

- Automatically loaded when analyzing multi-system architecture, breaking changes, complex migrations, or security vulnerabilities.

Process Transparency Harness Guard (v2.2.0)

Origin: Q9 — Discovered when Flash 3.6 Medium executed Tier Detection correctly but skipped artifact creation.

Severity: 🔴 Mandatory — applies to ALL models executing this skill.

Guard 1: Artifact Creation Enforcement

When this skill is activated inside a workflow that creates artifacts (e.g., /brainstorm, /sysdesign, /fix):

• Agent MUST create or append to the workflow's artifact file BEFORE entering Phase 1.
• Agent MUST NOT run the 4-phase cycle in <thought> only — the process MUST be visible in the artifact.
• If the calling workflow has no artifact mechanism, Agent MUST output phases directly in the chat response.

Guard 2: Phase Skip Detection

Agent MUST execute ALL phases (Step 0, Phase 1, Phase 2, Phase 3, Phase 4). If any phase is skipped:

> ⚠️ PHASE SKIPPED: [Phase Name] — Reason: [why]

This warning MUST appear in the output (artifact or chat). Agent MUST NOT silently skip phases.

Valid skip reasons (exhaustive list):

• user-requested — User explicitly asked to skip
• empty-graph-downgrade — Graph exists but returned empty results (Phase 2-3 MCP skip)
• time-budget-exceeded — Context window approaching limit

Any other reason is a protocol violation.

Guard 3: Phase Logging in Artifacts

When writing to an artifact file, each phase MUST have its own section header:

## Step 0: Tier Detection Log
[Tier result table]
 
## Phase 1: Problem Decomposition & Invariants
[Root problem, sub-problems, invariants]
 
## Phase 2: Divergent Exploration & Scoring
[3 approaches, 5D Scoring Matrix]
 
## Phase 3: Red-Team & Stress Testing
[Stress tests, trade-off matrix]
 
## Phase 4: Convergence & Decision
[Selected approach, rationale, next steps]

Rationale: Users MUST be able to trace the full reasoning process by reading the artifact file alone, without needing access to the Agent's internal <thought> chain.

Step 0: Complexity Tier Detection (Pre-Cycle)

Timing: BEFORE the 4-phase reasoning cycle. Agent MUST determine the complexity tier to allocate the correct MCP budget.

Gate: Run Step 0 FIRST, then enter Phase 1 with the allocated budget.

Hybrid 3-Layer Detection Algorithm

Layer 1: Prompt Keyword Signals (40% weight, zero-cost)

Layer 2: Graph Stats (40% weight, 1 scout MCP call, only when `--graph`)

Scout call: graph_god_nodes(topN=3) → extract totalNodes, topGodEdges

No graph available? → Prompt score × 1.5, cap at Tier 2.

Layer 3: Agent Override (20% weight)

• Agent MAY upgrade/downgrade 1 level, MUST justify in CoT Summary
• CANNOT downgrade if prompt contains tier3 keywords

Score Mapping:

Mid-Session Escalation: If Phase 2 impact_analysis > 20 affected nodes AND Tier == 1 → upgrade Tier 1→2. Max 1 escalation per session.

Scout Call Budget Note: The Layer 2 scout call (graph_god_nodes) counts as 1 call from the Phase 1 budget. If no graph exists, the scout call is skipped and the budget is unchanged.

Reasoning Workflow (4-Phase Cycle)

When this skill is active, the Agent MUST execute the following 4 phases inside its internal reasoning process (<thought>) before outputting final proposals or writing artifacts.

┌─────────────────────────┐     ┌─────────────────────────┐
│  1. DECOMPOSE & BOUNDS  │ ──► │   2. DIVERGE & SCORE    │
└─────────────────────────┘     └─────────────────────────┘
                                             │
                                             ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│  4. CONVERGE & SYNTHESIZE │ ◄── │   3. RED-TEAM & STRESS  │
└─────────────────────────┘     └─────────────────────────┘
         │                                   ▲
         │    ┌───────────────────────┐       │
         └───►│  PHASE REENTRY (3→2) │───────┘
              │  IF reentry triggered │
              └───────────────────────┘

Graph-Enhanced CoT (MCP Integration)

Gate: Before starting the 4-phase cycle, Agent MUST check if the active project has a code-knowledge graph:

```bash

test -d "Projects/[project-name]/.beads/graph" || test -d "Projects/[project-name]/repo/.beads/graph"

```

- IF graph exists → Agent MUST use MCP tools to ground each reasoning phase in real codebase data (see per-phase MCP table below). This prevents hallucinated architectural assumptions.

- IF no graph → Agent runs the protocol as pure reasoning. No MCP calls.

Adaptive MCP Budget Allocation (Per Tier)

Budget Rule: Agent MUST track MCP call count per phase. When phase budget is exhausted, move to next phase. Audit memory_push calls (kind: cot-audit) are system overhead and do NOT count against the tier budget.

Tier 1 — Simple (9 calls total)

Tier 2 — Moderate (14 calls total)

Tier 3 — Complex (21 + 3 reentry calls)

Early Exit: Stop divergent exploration as soon as one approach scores ≥ 0.8 higher weighted score than others. Remaining budget is NOT carried forward.

Phase 1: Problem Decomposition & Invariants

1. Root Problem Formulation:

• What is the core problem behind the user request? (Separate symptoms from underlying causes).
• What domain boundaries and systems are touched?

1. Invariants & Safety Guards Check:

• List workspace invariants (Kernel rules, governance, project rules) that MUST NOT be broken.
• Verify data safety, security parameters, and non-negotiable constraints.

1. Implicit Assumptions Audit:

• Identify unstated assumptions in the request or environment.
• Mark assumptions that require empirical verification via tools (view_file, grep_search).
• IF graph available: Use graph_query to locate architectural nodes related to the problem domain. Use memory_search to surface past decisions and friction on similar topics — avoid repeating solved problems.

Phase 2: Divergent Exploration & Multi-Perspective Scoring

1. Generate 3+ Distinct Approaches:

• Approach A (Conservative): Minimal change, lowest blast radius, leverages existing patterns.
• Approach B (Balanced/Optimal): Balanced structural improvement, maintainable long-term.
• Approach C (Aggressive/Redesign): Comprehensive refactor, decouples dependencies, maximum scalability.

1. Multi-Dimensional Scoring Matrix:

Score each approach on a scale of 1-5 across core engineering dimensions:

1. Token Overhead Guard & Reasoning Scope Limits:

• Limit: Keep internal reasoning inside <thought> under 300 lines (approx. 1,500 tokens).
• Exit Criteria: Stop divergent exploration as soon as one approach scores ≥ 0.8 higher weighted score than others.

Phase 3: Red-Teaming & Stress Testing

1. Failure Mode Analysis:

• How will this solution break under 10x scale, high concurrency, or network failures?
• What happens if an external dependency times out or returns unexpected state?

1. Edge Cases & Race Conditions:

• Null/Empty states, malformed input, missing config, authorization boundary bypasses.

1. Trade-Off Matrix Construction:

• Explicitly articulate what is being sacrificed for what (e.g., "Trading short-term dev speed for long-term schema safety").

Phase 4: Convergence & Decision Synthesis

1. Selection Rationale:

• Select the single optimal approach based on Phase 2 scoring and Phase 3 stress testing.
• Justify why discarded alternatives were rejected.

1. Execution Steps & Verification Plan:

• Break down the winning approach into atomic, verifiable implementation tasks.
• Define exact verification criteria (unit tests, static checks, manual inspection).

1. Memory Persistence (IF graph available):

Push the CoT decision into the knowledge graph via MCP memory_push:

• kind: cot-decision
• content: Root Problem + Selected Approach (A/B/C) + 5D Weighted Score + Critical Trade-Offs
• sessionId: Current session identifier
• metadata: { "cotDepth": 4, "scoringDimensions": 5, "selectedApproach": "[A/B/C]", "weightedScore": [N.NN], "doorType": "[one-way/two-way]", "mcp_evidence": [true/false] }

> This enables future sessions to retrieve architectural reasoning via memory_search(query, category: "cot-decision").

1. Structured CoT Artifact Section:

Format key insights to present to the user or append to the target document (brainstorm, sysdesign, research).

Phase Reentry Protocol