The Art of Problem Description: From Traditional Requirements to AI Prompt Engineering

Introduction: The Evolution of a Critical Skill

Historically, the Problem Description (PD) was the foundational artifact in Systems Analysis. It served as the single source of truth for deriving use cases, business process models (BPMN), class diagrams, and database schemas. A vague PD meant scope creep; a precise PD meant a successful build.

Today, with Generative AI, the Problem Description has not become obsolete; it has become the prompt.

AI models are essentially “requirement engines.” They cannot read your mind, but they can execute instructions with superhuman speed if those instructions are structured like a rigorous problem description. Writing a PD for AI requires the same analytical discipline as writing one for a development team, but with added layers of context regarding output format, constraints, and iterative refinement.

This guide bridges traditional systems analysis and modern AI prompting, providing a comprehensive framework for writing Problem Descriptions that yield high-quality diagrams, code, and strategic insights.

1. Key Concepts of Effective Problem Descriptions

Whether targeting human analysts or LLMs, four pillars support a robust PD:

1. Contextual Anchoring

• Traditional: Business background, stakeholders, regulatory environment.

• AI Usage: Persona definition, domain expertise level, target audience for the output.

• Why it matters: Without context, AI defaults to generic averages. “Design a login system” yields a student project; “Design a HIPAA-compliant patient portal login for elderly users with low digital literacy” yields a specialized architectural pattern.

2. Structural Decomposition

• Traditional: Breaking problems into functional/non-functional requirements, actors, and entities.

• AI Usage: Chain-of-Thought (CoT) structuring, step-by-step reasoning requests, modular prompting.

• Why it matters: AI struggles with monolithic complexity. Decomposing the PD helps the model maintain coherence over long outputs.

3. Constraint Specification

• Traditional: Budget, timeline, tech stack, compliance standards.

• AI Usage: Output format (Mermaid, PlantUML, JSON), style guidelines, forbidden patterns, token limits.

• Why it matters: Constraints force creativity and precision. Unconstrained AI generates verbose, often unusable artifacts.

4. Acceptance Criteria

• Traditional: Definition of Done, test cases, KPIs.

• AI Usage: Validation checks, self-correction prompts, expected structure verification.

• Why it matters: You must define what “good” looks like before generation begins to enable effective iteration.

2. Framework: The C.R.E.F.O. Model for AI Problem Descriptions

Adapted from traditional requirements gathering, use this template for AI tasks:

3. Usage Cases & Examples

Case A: Generating UML Class Diagrams

Challenge: AI often creates overly complex or syntactically incorrect diagrams when given vague domain descriptions.

❌ Weak Problem Description

“Create a class diagram for an e-commerce system.”

✅ Comprehensive Problem Description

CONTEXT: You are a Domain-Driven Design expert. We are building a B2B wholesale 
e-commerce platform where pricing is contract-based, not catalog-based.

REQUIREMENTS: Model the core ordering bounded context. Focus on the relationship 
between Contracts, PriceLists, Products, and Orders. Do NOT model UI or payment processing.

ENTITIES & RULES:
- Contract: Has effective dates, belongs to one CustomerAccount
- PriceList: Linked to Contract, contains tiered pricing rules
- OrderLine: Must validate price against active Contract at time of creation
- CustomerAccount: Can have multiple Contracts (current/historical)

FORMAT: Mermaid classDiagram syntax. Include visibility modifiers (+/-/#). 
Show multiplicity on ALL associations. Use notes for complex business rules.

CONSTRAINTS: Maximum 12 classes. Apply SOLID principles. No inheritance 
deeper than 2 levels. Prefer composition over inheritance.

VALIDATION: After generating, list 3 potential design weaknesses in this model.

Case B: Business Process Modeling (BPMN)

Challenge: AI confuses BPMN notation and misses exception paths.

✅ Comprehensive Problem Description

CONTEXT: Healthcare insurance claims processing. Audience: Compliance auditors 
and junior developers. Tone: Formal and precise.

TASK: Create a BPMN 2.0 compliant process diagram for "Prior Authorization Request."

PROCESS SCOPE:
START: Physician submits auth request via EHR integration
END: Decision communicated back to EHR + notification sent to member

KEY DECISION POINTS:
1. Is procedure covered under member's plan? (If no → auto-deny + appeal path)
2. Is clinical documentation complete? (If no → pend to nurse reviewer)
3. Does it require medical director review? (Threshold: >$50K or experimental)

EXCEPTION HANDLING: Model timeout events for each review stage (48hr SLA). 
Model escalation path if SLA breached.

FORMAT: Mermaid flowchart with BPMN-like styling. Use subgraphs for 
"Clinical Review" and "Administrative Validation" lanes.

OUTPUT REQUIREMENT: Provide the diagram code AND a markdown table mapping 
each decision node to the specific policy document section that governs it.

Case C: Deriving User Stories & Acceptance Criteria

Challenge: AI generates generic stories lacking testability.

✅ Comprehensive Problem Description

CONTEXT: Agile team migrating legacy COBOL payroll system to cloud-native. 
Team uses Gherkin/Cucumber BDD.

INPUT: [Paste excerpt of legacy system specification or interview transcript]

TASK: Extract user stories for the "Tax Withholding Calculation" module.

REQUIREMENTS PER STORY:
- Follow INVEST criteria
- Title format: As a [role], I want [capability], so that [business value]
- Acceptance Criteria: Minimum 5 Gherkin scenarios per story
- Include edge cases: Multi-state employees, retroactive pay adjustments, 
  garnishment caps, tax treaty exemptions

CONSTRAINTS: Each story must be completable in ≤3 days. Flag any story 
that seems too large with "[NEEDS SPLITTING]" tag.

FORMAT: Structured markdown with YAML frontmatter containing:
  - story_id
  - priority (MoSCoW)
  - estimated_points
  - dependencies

Case D: System Architecture Decision Records (ADR)

Challenge: Getting AI to reason about tradeoffs rather than just listing options.

✅ Comprehensive Problem Description

CONTEXT: We're choosing an event streaming platform for IoT telemetry 
(10M devices, 50K msgs/sec peak). Team has strong Kafka experience but 
management wants lower operational overhead.

TASK: Write an ADR comparing Apache Kafka vs. AWS Kinesis vs. Pulsar.

STRUCTURE (Follow Michael Nygard's ADR template):
1. Title & Status
2. Context (include our specific constraints below)
3. Decision Drivers (weighted)
4. Options Considered (pros/cons matrix)
5. Decision + Rationale
6. Consequences (positive AND negative)

DECISION DRIVERS (Weighted):
- Operational complexity (35%) - team is small (3 engineers)
- Cost at scale (25%)
- Message ordering guarantees (20%)
- Vendor lock-in risk (15%)
- Community/ecosystem (5%)

CONSTRAINT: Be brutally honest about downsides. Do not recommend based 
on popularity alone. If none are suitable, say so and suggest alternatives.

TONE: Technical, evidence-based, no marketing language.

4. Tips & Tricks

🎯 Precision Techniques

1. Define Your Ontology First: Before asking for any diagram, ask the AI to create a glossary/domain model. Align on terminology before generating artifacts. “First, define the key entities and their relationships in bullet points. Wait for my approval before generating the diagram.”

2. Negative Constraints Are Powerful: Telling AI what NOT to do is often more effective than what TO do. “Do not include CRUD operations in this sequence diagram. Do not use inheritance. Do not assume synchronous communication.”

3. Provide Anti-Examples: Show what bad output looks like. “Here is an example of an overly complex diagram we rejected last week [paste]. Avoid this pattern because…”

4. Use Structured Input Formats: Feed requirements as YAML, JSON, or numbered lists rather than prose. AI parses structured data more reliably.

5. Iterative Refinement Protocol: Never accept first-pass output for complex diagrams. Build refinement into your PD: “After generating, critique your own output against these 5 quality criteria. Then regenerate addressing all identified issues.”

⚠️ Common Pitfalls to Avoid

5. Guidelines Checklist

Before submitting any Problem Description to AI, verify:

• Role/Persona defined with appropriate expertise level

• Business context provided (not just technical specs)

• Scope boundaries explicitly stated (in/out of scope)

• Key entities/terms defined or referenced

• Output format specified with syntax/version details

• Constraints listed (technical, business, stylistic)

• Quality criteria defined for self-evaluation

• Edge cases/exceptions addressed

• Decomposition strategy planned for complex outputs

• Iteration protocol established

6. The Meta-Skill: Problem Description as Thinking Tool

The most important insight: Writing a Problem Description for AI is primarily an exercise in clarifying your own thinking.

If you struggle to write a clear PD, you don’t have a prompting problem—you have a requirements problem. The AI merely exposes the ambiguity that would have caused issues downstream anyway.

Use this workflow:

1. Draft your PD

2. Ask AI: “What questions would you need answered to complete this task perfectly?”

3. Answer those questions, refining your PD

4. Only then request the actual deliverable

This turns AI into a requirements elicitation partner, not just a generation engine. The quality of your Problem Description remains, as it always has been, the single greatest predictor of success—whether your collaborator is human or artificial.

FORMAT REQUIREMENT: Generate the class diagram in PlantUML syntax 
compatible with Visual Paradigm import. Include all stereotype annotations 
(<<entity>>, <<service>>, <<repository>>). Use VP-supported relationship 
notations only. Do NOT use custom extensions or non-standard decorators.

class OrderService {
  +processOrder(order: Order): void
}
class Order {
  +orderDate: Date
}
OrderService --> Order : uses

<<service>> class OrderService {
  +processOrder(order: Order): void
}
<<entity>> class Order {
  +orderDate: Date
}
<<repository>> class OrderRepository {
  +findById(id: UUID): Optional<Order>
}
OrderService --> OrderRepository : depends on
OrderService ..> Order : uses [1..* creates]

This guide synthesizes best practices from traditional systems analysis (IEEE 830, BABOK, UML specifications) and modern AI prompt engineering research. Adapt the frameworks to your organizational context and continuously refine based on output quality feedback loops.

Related posts:

UML Diagram Generators vs. Full Modeling Platforms: Why One Isn’t Enough From Problem to Process: A UML Modeling Guide