problem-solving

What this skill does

# Problem-Solving Skill

> **Version:** 2.2.0
> **Framework:** Jerry Problem-Solving (PS)
> **Constitutional Compliance:** Jerry Constitution v1.0

## Document Audience (Triple-Lens)

This SKILL.md serves multiple audiences:

| Level | Audience | Sections to Focus On |
|-------|----------|---------------------|
| **L0 (ELI5)** | New users, stakeholders | [Purpose](#purpose), [When to Use](#when-to-use-this-skill), [Routing Disambiguation](#routing-disambiguation), [Quick Reference](#quick-reference) |
| **L1 (Engineer)** | Developers invoking agents | [Invoking an Agent](#invoking-an-agent), [Agent Details](#agent-details), [Adversarial Quality Mode](#adversarial-quality-mode) |
| **L2 (Architect)** | Workflow designers | [Orchestration Flow](#orchestration-flow), [State Passing](#state-passing-between-agents), [Adversarial Quality Mode](#adversarial-quality-mode) |

---

## Purpose

The Problem-Solving skill provides a structured framework for tackling complex problems through specialized agents. Each agent produces **persistent artifacts** that survive context compaction and build a knowledge base over time.

### Key Capabilities

- **Structured Research** - Gather and document findings with source citations
- **Deep Analysis** - Root cause analysis, trade-offs, gap analysis, risk assessment
- **Architecture Decisions** - ADRs using Nygard format with L0/L1/L2 explanations
- **Validation** - Constraint verification with traceability matrices
- **Synthesis** - Cross-document pattern extraction and knowledge generation
- **Reviews** - Code, design, architecture, and security quality assessment
- **Investigations** - Failure analysis using 5 Whys, Ishikawa, FMEA
- **Reporting** - Status reports with health metrics and progress tracking

---

## When to Use This Skill

Activate when:

- Starting research on a new technology or approach
- Analyzing a problem to find root causes
- Making architectural decisions that need documentation
- Validating that constraints are satisfied
- Synthesizing findings across multiple documents
- Reviewing code, designs, or architecture
- Investigating failures or incidents
- Generating status or progress reports

---

## Available Agents

| Agent | Role | Output Location |
|-------|------|-----------------|
| `ps-researcher` | Research Specialist - Gathers information with citations | `docs/research/` |
| `ps-analyst` | Analysis Specialist - Deep analysis (5 Whys, FMEA, trade-offs) | `docs/analysis/` |
| `ps-architect` | Architecture Specialist - Creates ADRs with Nygard format | `docs/decisions/` |
| `ps-critic` | **Quality Evaluator - Iterative refinement with quality scores** | `docs/critiques/` |
| `ps-validator` | Validation Specialist - Verifies constraints with evidence | `docs/analysis/` |
| `ps-synthesizer` | Synthesis Specialist - Pattern extraction across documents | `docs/synthesis/` |
| `ps-reviewer` | Review Specialist - Code/design/security quality reviews | `docs/reviews/` |
| `ps-investigator` | Investigation Specialist - Root cause of failures | `docs/investigations/` |
| `ps-reporter` | Reporting Specialist - Status and progress reports | `docs/reports/` |

All agents produce output at three levels:
- **L0 (ELI5):** Executive summary for non-technical stakeholders
- **L1 (Software Engineer):** Technical implementation details
- **L2 (Principal Architect):** Strategic implications and trade-offs

---

## Invoking an Agent

### Option 1: Natural Language Request

Simply describe what you need:

```
"Research best practices for event sourcing in Python"
"Analyze the trade-offs between SQLite and PostgreSQL for this use case"
"Create an ADR for choosing Redis as our caching layer"
"Validate that all domain constraints are met"
"Investigate why the API timeout occurred"
```

The orchestrator will select the appropriate agent based on keywords and context.

### Option 2: Explicit Agent Request

Request a specific agent:

```
"Use ps-researcher to explore graph database options"
"Have ps-analyst do a 5 Whys on the login failures"
"I need ps-architect to create an ADR for the new persistence layer"
```

### Option 3: Task Tool Invocation

For programmatic invocation within workflows:

```python
Task(
    description="ps-researcher: Graph databases",
    subagent_type="general-purpose",
    prompt="""
You are the ps-researcher agent (v2.0.0).

## PS CONTEXT (REQUIRED)
- **PS ID:** work-024
- **Entry ID:** e-101
- **Topic:** Graph Database Options

## MANDATORY PERSISTENCE (P-002)
Create file at: docs/research/work-024-e-101-graph-databases.md

## RESEARCH TASK
Research graph database options for the Jerry framework.
Focus on: Gremlin compatibility, Python support, embedded options.
"""
)
```

---

## Orchestration Flow

### Sequential Chain Example

For complex problems requiring multiple perspectives:

```
User Request: "I need to understand why our tests are slow and fix it"

1. ps-researcher → Gather data on test execution patterns
   Output: docs/research/work-024-e-001-test-performance.md

2. ps-analyst → Apply 5 Whys to identify root cause
   Output: docs/analysis/work-024-e-002-root-cause.md

3. ps-architect → Create ADR for proposed solution
   Output: docs/decisions/work-024-e-003-adr-test-optimization.md

4. ps-validator → Verify solution meets constraints
   Output: docs/analysis/work-024-e-004-validation.md
```

### State Passing Between Agents

Agents can reference each other's output using state keys:

| Agent | Output Key | Provides |
|-------|------------|----------|
| ps-researcher | `researcher_output` | Research findings, sources |
| ps-analyst | `analyst_output` | Root cause, recommendations |
| ps-architect | `architect_output` | Decision, alternatives |
| ps-validator | `validator_output` | Validation status, gaps |
| ps-synthesizer | `synthesizer_output` | Patterns, themes |
| ps-reviewer | `reviewer_output` | Findings, assessment |
| ps-investigator | `investigator_output` | Root cause, corrective actions |
| ps-reporter | `reporter_output` | Metrics, health status |

---

## Tool Invocation Examples

Each agent uses the allowed tools differently. Here are concrete examples:

### Research Tasks (ps-researcher)

```
1. Find existing research documents:
   Glob(pattern="docs/research/**/*.md")
   → Returns list of prior research to reference

2. Search for industry sources:
   WebSearch(query="event sourcing Python patterns 2026")
   → Find current industry guidance

3. Create research output (MANDATORY per P-002):
   Write(
       file_path="docs/research/work-024-e-001-event-sourcing.md",
       content="# Research: Event Sourcing in Python\n\n## L0: Executive Summary\n..."
   )
   → Persist findings - transient output VIOLATES P-002
```

### Analysis Tasks (ps-analyst)

```
1. Find prior analyses to reference:
   Glob(pattern="docs/analysis/**/*.md")

2. Search for specific patterns in codebase:
   Grep(pattern="try|except|raise", path="src/", output_mode="content", -C=2)
   → Find error handling patterns for root cause analysis

3. Read existing documentation:
   Read(file_path="docs/research/work-024-e-001-event-sourcing.md")
   → Load prior research to inform analysis

4. Create analysis output (MANDATORY per P-002):
   Write(
       file_path="docs/analysis/work-024-e-002-root-cause.md",
       content="# Root Cause Analysis: Build Failures\n\n## L0: Executive Summary\n..."
   )
```

### Architecture Tasks (ps-architect)

```
1. Find existing ADRs for consistency:
   Glob(pattern="docs/decisions/**/*.md")
   → Reference prior decisions

2. Research architectural patterns:
   WebFetch(url="https://martinfowler.com/eaaDev/EventSourcing.html",
            prompt="Extract key benefits and trade-offs of event sourcing")

3. Create ADR output (MANDATORY per P-002):
   Write(
       file_path="docs/decisions/work-024-e-003-adr-persistence.md",
       content="# ADR-042: Use Event Sourcing for Task History\n\n## Status\nPROPOSED\n..."
   )
```

---

## Mandatory Persistence (P-002)

All