# BrutalHonesty Module API Documentation
Version: 3.0.0
The BrutalHonesty module applies adversarial thinking to identify weaknesses,
challenge assumptions aggressively, and score confidence with skepticism.
## Table of Contents
1. [Module Overview](#module-overview)
2. [Configuration](#configuration)
3. [Core Types](#core-types)
4. [Methods](#methods)
5. [Usage Examples](#usage-examples)
6. [Error Handling](#error-handling)
## Module Overview
BrutalHonesty implements red-team analysis that finds flaws before others do,
challenges assumptions aggressively, and adjusts confidence scores based on
identified weaknesses. It serves as a critical thinking safeguard.
Key capabilities:
- Assumption hunting and questioning
- Flaw categorization by severity and type
- Skeptical confidence scoring
- Devil's advocate counter-argumentation
- Cognitive bias detection
- Strength identification alongside weaknesses
## Configuration
### BrutalHonestyConfig
Configuration struct controlling BrutalHonesty critique severity and focus.
```rust
pub struct BrutalHonestyConfig {
pub severity: CritiqueSeverity,
pub enable_devil_advocate: bool,
pub detect_cognitive_biases: bool,
pub min_flaw_severity: FlawSeverity,
pub enable_strengths_analysis: bool,
pub timeout_ms: u64,
}
```
#### Fields
| `severity` | `CritiqueSeverity` | Yes | `Standard` | Critique harshness level. Controls skepticism intensity. |
| `enable_devil_advocate` | `bool` | Yes | `true` | Enable devil's advocate analysis. Challenges position rigorously. |
| `detect_cognitive_biases` | `bool` | Yes | `true` | Enable cognitive bias detection. Identifies reasoning flaws. |
| `min_flaw_severity` | `FlawSeverity` | Yes | `Minor` | Minimum flaw severity to report. Filters noise. |
| `enable_strengths_analysis` | `bool` | Yes | `true` | Also identify strengths. Provides balanced critique. |
| `timeout_ms` | `u64` | Yes | `20000` | Critique timeout in milliseconds. Prevents hanging operations. |
#### Implementation
```rust
impl Default for BrutalHonestyConfig {
fn default() -> Self {
Self {
severity: CritiqueSeverity::Standard,
enable_devil_advocate: true,
detect_cognitive_biases: true,
min_flaw_severity: FlawSeverity::Minor,
enable_strengths_analysis: true,
timeout_ms: 20000,
}
}
}
impl BrutalHonestyConfig {
/// Gentle critique mode - constructive feedback focus
pub fn gentle() -> Self {
Self {
severity: CritiqueSeverity::Gentle,
enable_devil_advocate: false,
detect_cognitive_biases: false,
min_flaw_severity: FlawSeverity::Moderate,
enable_strengths_analysis: true,
timeout_ms: 15000,
}
}
/// Ruthless critique mode - maximum skepticism
pub fn ruthless() -> Self {
Self {
severity: CritiqueSeverity::Ruthless,
enable_devil_advocate: true,
detect_cognitive_biases: true,
min_flaw_severity: FlawSeverity::Minor,
enable_strengths_analysis: false,
timeout_ms: 30000,
}
}
}
```
## Core Types
### BrutalHonesty
Main module struct implementing the ThinkToolModule trait.
```rust
pub struct BrutalHonesty {
config: ThinkToolModuleConfig,
brutal_config: BrutalHonestyConfig,
}
```
#### Fields
| `config` | `ThinkToolModuleConfig` | Standard module configuration metadata |
| `brutal_config` | `BrutalHonestyConfig` | BrutalHonesty-specific configuration parameters |
### BrutalHonestyResult
Structured output from BrutalHonesty execution containing critique analysis.
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BrutalHonestyResult {
pub verdict: CritiqueVerdict,
pub analysis: String,
pub flaws: Vec<DetectedFlaw>,
pub strengths: Vec<IdentifiedStrength>,
pub assumptions: Vec<ImplicitAssumption>,
pub devil_advocate: Option<String>,
pub confidence: f64,
pub metadata: CritiqueMetadata,
}
```
#### Fields
| `verdict` | `CritiqueVerdict` | Overall critique judgment |
| `analysis` | `String` | Detailed critique analysis |
| `flaws` | `Vec<DetectedFlaw>` | Identified weaknesses |
| `strengths` | `Vec<IdentifiedStrength>` | Recognized positive aspects |
| `assumptions` | `Vec<ImplicitAssumption>` | Unstated assumptions found |
| `devil_advocate` | `Option<String>` | Devil's advocate counter-argument |
| `confidence` | `f64` | Adjusted confidence score |
| `metadata` | `CritiqueMetadata` | Execution metadata |
### CritiqueVerdict
Overall judgment of the critique analysis.
```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CritiqueVerdict {
StronglyValid, // Highly defensible position
ModeratelyValid, // Reasonably defensible with caveats
WeaklyValid, // Barely defensible
FundamentallyFlawed, // Serious structural problems
IrredeemablyFlawed, // Beyond reasonable defense
}
```
### CritiqueSeverity
Severity level controlling critique harshness and confidence adjustment.
```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CritiqueSeverity {
Gentle, // Gentle critique - focus on constructive feedback (-10% confidence)
Standard, // Standard critique - balanced flaw detection (-20% confidence)
#[default]
Harsh, // Harsh critique - aggressive assumption challenging (-35% confidence)
Ruthless, // Ruthless critique - no mercy, find every flaw (-50% confidence)
}
```
#### Confidence Adjustments
| `Gentle` | Constructive feedback focus | -10% |
| `Standard` | Balanced flaw detection | -20% |
| `Harsh` | Aggressive assumption challenging | -35% |
| `Ruthless` | No mercy, find every flaw | -50% |
### DetectedFlaw
Identification of specific weaknesses with categorization and severity.
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DetectedFlaw {
pub category: FlawCategory,
pub severity: FlawSeverity,
pub description: String,
pub examples: Vec<String>,
pub countermeasures: Vec<String>,
pub cognitive_bias: Option<CognitiveBias>,
}
```
#### Fields
| `category` | `FlawCategory` | Type of flaw detected |
| `severity` | `FlawSeverity` | Importance of flaw |
| `description` | `String` | Explanation of flaw |
| `examples` | `Vec<String>` | Specific instances |
| `countermeasures` | `Vec<String>` | Ways to address flaw |
| `cognitive_bias` | `Option<CognitiveBias>` | Related cognitive bias |
### FlawCategory
Categories of flaws detected during critique analysis.
```rust
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FlawCategory {
Logical, // Fallacies, contradictions, non-sequiturs
Evidential, // Missing data, weak sources, cherry-picking
Assumption, // Unexamined premises, hidden biases
Scope, // Overgeneralization, false dichotomies
Temporal, // Recency bias, ignoring history
Adversarial, // Vulnerabilities to counter-arguments
Completeness, // Missing considerations, blind spots
}
```
### FlawSeverity
Severity levels for prioritizing flaw remediation.
```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FlawSeverity {
Minor, // Minor issue - worth noting but not critical
Moderate, // Moderate issue - should be addressed
Major, // Major issue - significantly weakens the argument
Critical, // Critical issue - fundamentally undermines the position
}
```
### IdentifiedStrength
Positive aspects identified during critique for balanced analysis.
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct IdentifiedStrength {
pub category: StrengthCategory,
pub description: String,
pub evidence: Vec<String>,
pub significance: f64,
}
```
#### Fields
| `category` | `StrengthCategory` | Type of strength identified |
| `description` | `String` | Explanation of strength |
| `evidence` | `Vec<String>` | Supporting examples |
| `significance` | `f64` | Importance weight (0.0-1.0) |
### StrengthCategory
Categories of positive aspects identified during critique.
```rust
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StrengthCategory {
Logical, // Sound reasoning, valid conclusions
Evidential, // Strong evidence, credible sources
Innovative, // Novel ideas, creative approaches
Practical, // Real-world applicability
Coherent, // Well-structured, internally consistent
Comprehensive, // Thorough coverage of considerations
}
```
### ImplicitAssumption
Unstated assumptions discovered during critique analysis.
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ImplicitAssumption {
pub statement: String,
pub category: AssumptionCategory,
pub challenge: String,
pub impact: AssumptionImpact,
pub alternatives: Vec<String>,
}
```
#### Fields
| `statement` | `String` | The unstated assumption |
| `category` | `AssumptionCategory` | Classification of assumption |
| `challenge` | `String` | How to question this assumption |
| `impact` | `AssumptionImpact` | Effect of assumption being wrong |
| `alternatives` | `Vec<String>` | Alternative assumptions to consider |
### AssumptionCategory
Classification of assumption types for targeted analysis.
```rust
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AssumptionCategory {
Factual, // Assumed facts about the world
Causal, // Cause-and-effect relationships
Value, // Moral or ethical presuppositions
Methodological, // Assumed approaches or techniques
Temporal, // Time-related assumptions
Cultural, // Culture-specific presuppositions
}
```
### AssumptionImpact
Assessment of consequences if an assumption proves incorrect.
```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AssumptionImpact {
Minimal, // Little effect on conclusions
Moderate, // Some effect on conclusions
Significant, // Major effect on conclusions
Catastrophic, // Completely invalidates conclusions
}
```
### CognitiveBias
Identification of psychological reasoning biases affecting analysis.
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CognitiveBias {
pub bias: BiasType,
pub description: String,
pub examples: Vec<String>,
pub mitigation: String,
pub confidence: f64,
}
```
#### Fields
| `bias` | `BiasType` | Type of cognitive bias |
| `description` | `String` | Explanation of bias |
| `examples` | `Vec<String>` | Instances in the analysis |
| `mitigation` | `String` | How to counteract this bias |
| `confidence` | `f64` | Confidence in bias identification |
### BiasType
Types of cognitive biases detectable by BrutalHonesty.
```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BiasType {
Confirmation, // Favoring confirming evidence
Anchoring, // Over-relying on initial information
Availability, // Judging by memorable examples
Hindsight, // Believing past events were predictable
Overconfidence, // Excessive belief in own judgments
StatusQuo, // Preferring things to stay the same
Bandwagon, // Following popular opinion
SunkCost, // Continuing due to prior investment
Survivorship, // Ignoring failures in analysis
FalseConsensus, // Overestimating agreement with others
}
```
### CritiqueMetadata
Execution metadata and performance statistics.
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CritiqueMetadata {
pub execution_time_ms: u64,
pub flaws_analyzed: usize,
pub strengths_identified: usize,
pub assumptions_exposed: usize,
pub biases_detected: usize,
pub devil_advocate_used: bool,
}
```
#### Fields
| `execution_time_ms` | `u64` | Total execution time in milliseconds |
| `flaws_analyzed` | `usize` | Number of flaws examined |
| `strengths_identified` | `usize` | Number of positive aspects found |
| `assumptions_exposed` | `usize` | Number of unstated assumptions revealed |
| `biases_detected` | `usize` | Number of cognitive biases identified |
| `devil_advocate_used` | `bool` | Whether devil's advocate analysis was performed |
## Methods
### BrutalHonesty::new()
Create a new BrutalHonesty module with default configuration.
```rust
pub fn new() -> Self
```
Returns: `BrutalHonesty` instance with default settings.
Example:
```rust
let module = BrutalHonesty::new();
assert_eq!(module.name(), "BrutalHonesty");
assert_eq!(module.version(), "3.0.0");
```
### BrutalHonesty::with_config()
Create a new BrutalHonesty module with custom configuration.
```rust
pub fn with_config(config: BrutalHonestyConfig) -> Self
```
Parameters:
- `config`: `BrutalHonestyConfig` - Custom configuration parameters
Returns: `BrutalHonesty` instance with specified configuration.
Example:
```rust
let config = BrutalHonestyConfig::ruthless();
let module = BrutalHonesty::with_config(config);
```
### BrutalHonesty::critique()
Direct critique of a statement or position.
```rust
pub fn critique(&self, statement: &str) -> Result<BrutalHonestyResult>
```
Parameters:
- `statement`: `&str` - Statement or position to critique
Returns: `Result<BrutalHonestyResult>` - Critique results or error.
Example:
```rust
let module = BrutalHonesty::new();
let result = module.critique("Our startup will succeed because we have the best team")?;
```
### BrutalHonesty::execute()
Execute the BrutalHonesty module synchronously.
```rust
impl ThinkToolModule for BrutalHonesty {
fn execute(&self, context: &ThinkToolContext) -> Result<ThinkToolOutput>
}
```
Parameters:
- `context`: `&ThinkToolContext` - Execution context with statement to critique
Returns: `Result<ThinkToolOutput>` - Structured output or error.
Example:
```rust
let module = BrutalHonesty::new();
let context = ThinkToolContext::new("Blockchain will revolutionize everything");
let result = module.execute(&context)?;
```
### BrutalHonesty::config()
Get the module configuration.
```rust
pub fn config(&self) -> &BrutalHonestyConfig
```
Returns: `&BrutalHonestyConfig` - Reference to current configuration.
Example:
```rust
let module = BrutalHonesty::new();
let config = module.config();
assert_eq!(config.severity, CritiqueSeverity::Standard);
```
## Usage Examples
### Basic Critique
```rust
use reasonkit::thinktool::modules::{BrutalHonesty, ThinkToolContext, ThinkToolModule};
// Create module with default settings
let module = BrutalHonesty::new();
// Direct critique of a statement
let result = module.critique("We should invest heavily in AI because it's the future")?;
// Check overall verdict
match result.verdict {
CritiqueVerdict::StronglyValid => println!("Position is highly defensible"),
CritiqueVerdict::FundamentallyFlawed => println!("Serious structural problems detected"),
_ => println!("Mixed assessment: {:?}", result.verdict),
}
// Examine detected flaws
for flaw in &result.flaws {
println!("Flaw ({}): {}", flaw.severity, flaw.description);
// Focus on major/critical flaws
if flaw.severity >= FlawSeverity::Major {
println!(" Countermeasures: {:?}", flaw.countermeasures);
}
}
// Review identified strengths for balanced perspective
for strength in &result.strengths {
println!("Strength: {}", strength.description);
}
```
### Context-Based Execution
```rust
use reasonkit::thinktool::modules::{BrutalHonesty, ThinkToolContext, ThinkToolModule};
// Create module with harsh critique configuration
let module = BrutalHonesty::with_config(
BrutalHonestyConfig {
severity: CritiqueSeverity::Harsh,
detect_cognitive_biases: true,
enable_devil_advocate: true,
..Default::default()
}
);
// Prepare context with complex proposition
let context = ThinkToolContext::new(
"Our company's strategy of rapid expansion into all markets simultaneously \
will maximize shareholder value while minimizing competitive risk"
);
// Execute harsh critique
let result = module.execute(&context)?;
// Access devil's advocate perspective
if let Some(devil_advocate) = result.get_str("devil_advocate") {
println!("Devil's advocate position:\n{}", devil_advocate);
}
// Analyze confidence adjustment
let base_confidence = 0.9; // Hypothetical original confidence
let adjusted_confidence = result.confidence;
println!("Confidence adjusted from {:.1}% to {:.1}% due to critique",
base_confidence * 100.0, adjusted_confidence * 100.0);
```
### Ruthless Critique Configuration
```rust
use reasonkit::thinktool::modules::{BrutalHonesty, BrutalHonestyConfig, ThinkToolContext};
// Configure for maximum skepticism
let config = BrutalHonestyConfig::ruthless();
let module = BrutalHonesty::with_config(config);
// Critique high-stakes proposal
let context = ThinkToolContext::new(
"We should proceed with the merger despite regulatory concerns \
because the synergies will be enormous"
);
let result = module.execute(&context)?;
// Examine cognitive biases detected
let biases = result.get_array("biases").unwrap();
if !biases.is_empty() {
println!("Detected {} cognitive biases:", biases.len());
for bias in biases {
println!("- {}: {}",
bias.get("bias").unwrap().as_str().unwrap(),
bias.get("description").unwrap().as_str().unwrap());
}
}
// Review exposed assumptions
let assumptions = result.get_array("assumptions").unwrap();
println!("Exposed {} implicit assumptions:", assumptions.len());
for assumption in assumptions {
println!("- {}: {}",
assumption.get("statement").unwrap().as_str().unwrap(),
assumption.get("challenge").unwrap().as_str().unwrap());
}
```
## Error Handling
BrutalHonesty defines specific error types for critique failures:
### BrutalHonestyError
Enumeration of all possible module-specific errors.
```rust
#[derive(Error, Debug, Clone)]
pub enum BrutalHonestyError {
CritiqueGenerationFailed { reason: String },
DevilAdvocateFailed { reason: String },
BiasDetectionFailed { reason: String },
AssumptionExtractionFailed { reason: String },
CritiqueTimeout { duration_ms: u64 },
StatementFormatInvalid { message: String },
}
```
### Error Descriptions
| `CritiqueGenerationFailed` | `reason` | Unable to generate critique |
| `DevilAdvocateFailed` | `reason` | Devil's advocate analysis failed |
| `BiasDetectionFailed` | `reason` | Cognitive bias detection error |
| `AssumptionExtractionFailed` | `reason` | Could not identify assumptions |
| `CritiqueTimeout` | `duration_ms` | Critique generation exceeded timeout |
| `StatementFormatInvalid` | `message` | Malformed statement input |
### Error Conversion
All BrutalHonestyError variants are automatically converted to the standard Error type:
```rust
impl From<BrutalHonestyError> for Error {
fn from(err: BrutalHonestyError) -> Self {
Error::ThinkToolExecutionError(err.to_string())
}
}
```
### Handling Errors
```rust
use reasonkit::thinktool::modules::{BrutalHonesty, ThinkToolContext, BrutalHonestyError};
let module = BrutalHonesty::new();
let context = ThinkToolContext::new(""); // Empty statement
match module.execute(&context) {
Ok(result) => {
// Process successful result
println!("Critique completed with confidence: {:.2}", result.confidence);
}
Err(e) => {
// Handle specific BrutalHonesty errors
if let Some(bh_err) = e.downcast_ref::<BrutalHonestyError>() {
match bh_err {
BrutalHonestyError::StatementFormatInvalid { message } => {
eprintln!("Invalid statement format: {}", message);
}
BrutalHonestyError::CritiqueTimeout { duration_ms } => {
eprintln!("Critique timed out after {}ms", duration_ms);
}
BrutalHonestyError::CritiqueGenerationFailed { reason } => {
eprintln!("Failed to generate critique: {}", reason);
}
_ => eprintln!("BrutalHonesty error: {}", bh_err),
}
} else {
// Handle other errors
eprintln!("Other error: {}", e);
}
}
}
```
## Performance Considerations
1. **Critique Severity**: Choose appropriate severity level for use case
2. **Devil's Advocate**: Disable for faster execution when adversarial analysis isn't needed
3. **Bias Detection**: Can be disabled to reduce processing overhead
4. **Timeout Settings**: Set appropriate timeouts based on statement complexity
5. **Strengths Analysis**: Disable when focusing solely on weaknesses
## Integration Notes
When using BrutalHonesty in protocol execution:
```rust
use reasonkit::thinktool::{ProtocolExecutor, ProtocolInput};
// ProtocolExecutor handles LLM integration automatically
let executor = ProtocolExecutor::new()?;
let result = executor.execute(
"brutalhonesty",
ProtocolInput::query("Controversial statement to critique")
).await?;
```
The protocol-based approach provides:
- Automatic LLM selection for sophisticated critique generation
- Streaming output for real-time critique progress
- Built-in retry logic for failed critique steps
- Comprehensive execution tracing and audit capabilities
- Integration with memory layer for learning from past critiques