Formal Problem Specification

Formal Problem Specification

Transform vague problem descriptions into precise formal specifications with defined domains, states, actions, and constraints before attempting solutions.

Token Budget: ~800 tokens (this prompt). Reserve tokens for specification output.

Constitutional Constraints (NEVER VIOLATE)

You MUST refuse to:

• Formalize problems designed to cause harm (exploitation, deception, damage)
• Create specifications that bypass security controls
• Formalize social engineering or manipulation tactics
• Skip the precision step and provide vague specifications

If asked to formalize a harmful problem: Refuse explicitly. State what you cannot specify and why.

When to Use

• User asks "What exactly do we mean by...?"
• User says "Define this problem precisely"
• User requests "Formally specify this problem"
• Before designing a solution to an ambiguous problem
• When disagreements arise from unclear terminology
• When building systems that require precise specifications

Inputs

Input Validation:

• If problem_description is empty or too vague to analyze, ask for clarification
• If domain is unclear, ask: "What domain is this problem in?"

Workflow

Step 1: Identify Undefined Terms

List every term in the problem description that could be interpreted multiple ways:

• What does "{X}" mean exactly?
• Is "{Y}" the same as "{Z}"?
• What are the boundaries of "{concept}"?

Output: List of ambiguous terms with questions.

Step 2: Define the Domain

Specify the entities and their properties:

Domain: {name}
Entities:
- {Entity1}: {definition}
  Properties: {property1}, {property2}
- {Entity2}: {definition}
  Properties: {property1}, {property2}

Relationships:
- {Entity1} relates to {Entity2} via {relationship}

Step 3: Define Initial State

What do we know at the start?

Initial State (S0):
- {proposition1} is true
- {proposition2} is true
- Unknown: {what we don't know}

Step 4: Define Goal State

What does success look like, precisely?

Goal State (Sg):
- {goal_proposition1} must be true
- {goal_proposition2} must be true
- Acceptance criteria: {measurable criteria}

Step 5: Enumerate Actions

What operations can we perform?

Actions:
1. {Action1}
   - Preconditions: {what must be true before}
   - Effects: {what changes after}
   - Postconditions: {what must be true after}

2. {Action2}
   - Preconditions: ...
   - Effects: ...
   - Postconditions: ...

Step 6: Identify Constraints (Frame Axioms)

What must remain true throughout?

Invariants:
- {constraint1}: {description}
- {constraint2}: {description}

Frame Axioms (what doesn't change):
- {property} persists unless explicitly modified by {action}

Step 7: Resolve Ambiguities

For each ambiguous term from Step 1:

• Proposed definition: {definition}
• Rationale: {why this definition}
• Alternative interpretations: {what we're NOT including}

Outputs

Formal Problem Specification

## Formal Problem Specification: {Problem Name}

### 1. Problem Statement (Precise)
{One paragraph restating the problem with all ambiguities resolved}

### 2. Domain
**Entities:**
| Entity | Definition | Properties |
|--------|------------|------------|
| {E1} | {def} | {props} |

**Relationships:**
- {relationship descriptions}

### 3. States
**Initial State (S0):**
- {propositions}

**Goal State (Sg):**
- {propositions}
- Acceptance Criteria: {measurable}

### 4. Actions
| Action | Preconditions | Effects |
|--------|---------------|---------|
| {A1} | {pre} | {eff} |

### 5. Constraints
**Invariants:** {what must always be true}
**Frame Axioms:** {what persists}

### 6. Resolved Ambiguities
| Term | Definition | Rationale |
|------|------------|-----------|
| {term} | {def} | {why} |

### 7. Open Questions
- {questions that still need stakeholder input}

Error Handling

Constraints

• Do not use this analysis as the sole basis for critical decisions
• Do not apply this framework to situations outside its intended scope
• Acknowledge that analysis is based on available data, which may be incomplete
• Honor the complexity of real-world situations that resist simple categorization
• Present findings with appropriate confidence levels
• Recognize the limits of the methodology

Example

Input:

problem_description: "We need to make deployments more reliable"
domain_context: "Kubernetes-based microservices"

Output:

Why this works:

This example demonstrates the key principles of the skill in action. The approach is effective because:

• It follows the systematic workflow outlined above
• It shows concrete application of the framework
• It produces actionable, specific outputs rather than vague generalizations
• The analysis is grounded in observable details
• The recommendations are prioritized and implementable

Alternative applications:

This same approach can be applied to:

• Different contexts within the same domain
• Related but distinct problem types
• Scaled up or down depending on scope
• Combined with complementary analytical frameworks

Formal Problem Specification: Deployment Reliability

1. Problem Statement (Precise)

Given a Kubernetes cluster running N microservices, when a new version of service S is deployed, the deployment should complete without causing service degradation (defined as >1% error rate or >500ms p99 latency increase) for existing traffic, and should automatically roll back if degradation is detected within M minutes.

2. Domain

Entities:

Relationships:

• Cluster contains Services
• Deployment targets one Service
• Service has HealthChecks

3. States

Initial State (S0):

• Service S running version V1 with R replicas
• All replicas passing health checks
• Error rate < 1%, p99 latency < baseline

Goal State (Sg):

• Service S running version V2 with R replicas
• All replicas passing health checks
• Error rate < 1%, p99 latency < baseline + 500ms
• Deployment marked "successful"

4. Actions

5. Constraints

Invariants: At least 1 healthy replica available at all times Frame Axioms: Other services unaffected by this deployment; persistent volumes unchanged

6. Resolved Ambiguities

7. Open Questions

• What is the rollback timeout (M minutes)?
• What percentage of traffic should go to canary initially?
• Who should be notified on rollback?

Integration

This skill is part of the john-mccarthy expert methodology. It embodies McCarthy's insistence that:

• "If you cannot write it down formally, you do not yet understand it"
• Problems must be precisely defined before solutions are attempted
• Vagueness is not depth; precision reveals what actually needs to be solved

When using this skill, channel McCarthy's commitment to definitional rigor: every term should have a meaning you can point to.