Cognotik | TechnicalExplanationTask

⚙️ ExecutionConfig.json


{
  "topic": "Raft Consensus Algorithm",
  "target_audience": "software_engineer",
  "level_of_detail": "detailed_walkthrough",
  "include_code_examples": true,
  "use_analogies": true,
  "code_language": "kotlin",
  "define_terminology": true,
  "include_comparisons": true
}

→

👁️ Generated Explanation

# Understanding Raft Consensus

Explanation for: software_engineer

The Analogy: A Distributed Jury

Imagine a jury where members are in different rooms. To reach a verdict, they need a leader to coordinate votes...

Leader Election

enum class Role { FOLLOWER, CANDIDATE, LEADER }

Nodes start as followers and transition to candidates if they don't hear from a leader...

Live Results Showcase

Explore actual technical explanations generated by this task in the test workspace.

Configuration Parameters

Field	Type	Description
`topic` *	String	The complex technical subject to explain.
`target_audience`	String	Expertise level (layperson, beginner, intermediate, expert, manager, software_engineer, data_scientist). Default: `intermediate`.
`level_of_detail`	String	Depth of explanation (high_level_overview, moderate_detail, detailed_walkthrough, comprehensive). Default: `moderate_detail`.
`include_code_examples`	Boolean	Whether to include code snippets. Default: `true`.
`explanation_format`	String	Format (markdown, q_and_a, step_by_step, narrative, tutorial). Default: `markdown`.
`use_analogies`	Boolean	Whether to generate relatable analogies and metaphors. Default: `true`.
`include_visual_descriptions`	Boolean	Whether to include descriptions of diagrams or visualizations. Default: `true`.
`define_terminology`	Boolean	Whether to define key technical terms. Default: `true`.
`include_examples`	Boolean	Whether to include practical use cases. Default: `true`.
`include_comparisons`	Boolean	Whether to provide comparison with related concepts. Default: `true`.
`code_language`	String	Programming language for code examples.
`revision_passes`	Int	Number of iterative refinement passes (0-5). Default: `1`.
`input_files`	List<String>	Glob patterns for source files to use as context.
`related_files`	List<String>	Specific documentation files to reference.

Lifecycle Phases

Phase 1: Analysis & Outline

Analyzes the topic and creates a structured ExplanationOutline including key concepts, terminology, and analogy mappings.

Phase 2: Content Generation

Iteratively writes ExplanationSections for each concept in the outline, incorporating code snippets and takeaways.

Phase 3: Comparisons

Identifies related or commonly confused concepts and provides a contrast analysis.

Phase 4: Revision

Performs automated editorial passes to improve clarity, flow, and audience appropriateness.

Phase 5: Final Assembly

Compiles the final document with overview, terminology, content, and summary.

Embedded Invocation (Kotlin)

Use the UnifiedHarness to run this task in a headless environment (CI/CD, CLI).


import com.simiacryptus.cognotik.apps.general.UnifiedHarness
import com.simiacryptus.cognotik.plan.TaskType
import com.simiacryptus.cognotik.plan.tools.writing.TechnicalExplanationTask.TechnicalExplanationTaskExecutionConfigData
import com.simiacryptus.cognotik.plan.tools.writing.TechnicalExplanationTask.Companion.TechnicalExplanation
import java.io.File

val harness = UnifiedHarness(serverless = true, openBrowser = false)
harness.start()

val config = TechnicalExplanationTaskExecutionConfigData(
    topic = "Zero-Knowledge Proofs",
    target_audience = "beginner",
    level_of_detail = "moderate_detail",
    use_analogies = true,
    revision_passes = 2,
    input_files = listOf("src/crypto/*.kt")
)

harness.runTask(
    taskType = TechnicalExplanation,
    executionConfig = config,
    workspace = File("./docs/explanations")
)

CLI Example


java -jar cognotik-cli.jar \
  --task TechnicalExplanation \
  --topic "Garbage Collection in JVM" \
  --target_audience "software_engineer" \
  --workspace ./output