problem-to-solution

Problem To Solution

Quick Start

Use this skill to turn an ambiguous problem into a concise decision document for non-technical business stakeholders.

Store generated problem-to-solution briefs under the consuming repository's private lab root in problem-to-solutions/.

problem-to-solutions/<problem-slug>-problem-to-solution.md

Use templates/problem-to-solution-template.md as the output structure. Replace placeholders and drafting guidance with concrete content; do not leave unanswered sections unless the unknown is explicitly marked as TBD or an open question. Remove the ## Open Questions section when there are no open questions.

Problem-to-solution briefs are written for non-technical business stakeholders first. Architects and delivery teams should get enough context to act, but the opening sections must be easy for a business reader to scan, understand, and use in a decision meeting.

Do not write real-company decision context into this public toolkit repository.

Required Inputs

• Problem statement
• Decision needed
• Decision owner or forum
• Stakeholders and impacted groups
• Business or architecture context
• Constraints, assumptions, and non-goals
• Evaluation criteria
• Candidate solution options
• Recommendation and rationale after solution exploration is complete
• ADR link when the solution is decided

Workflow

1. Clarify the problem, why it matters now, who needs to decide, and when a decision is needed.
2. Ask for known constraints, non-goals, dependencies, risks, and stakeholder concerns when not already provided.
3. Read related architecture documents when paths are provided.
4. Validate terminology against <private-lab-root>/GLOSSARY.md when the brief uses domain-specific applications, capabilities, data objects, or jargon. Use ../ubiquitous-language/SKILL.md to clarify or update terminology before option brainstorming when important terms are missing, ambiguous, or overloaded.
5. Use ../grill-me/SKILL.md to pressure-test the problem framing, assumptions, constraints, stakeholder tensions, and evaluation criteria before settling on solution options.
6. Brainstorm 2-5 realistic solution options. Include a "do nothing" or "defer" option only when it is a plausible decision path.
7. Evaluate each option against the same criteria so comparisons are fair and decision-ready.
8. Write balanced pros and cons for each option. Avoid strawman alternatives.
9. Before writing a recommendation, use ../grill-me/SKILL.md for a dedicated exploration review of all options, pros, cons, assumptions, missing alternatives, hidden constraints, and stakeholder trade-offs. Ask questions one at a time and wait for feedback before concluding the review.
10. Revise the options, pros, cons, criteria, and open questions based on the grill-me session.
11. Only after the grill-me exploration review is complete, recommend one option, or a staged combination, with clear rationale, trade-offs, and conditions for success.
12. Create or update the problem-to-solution brief from templates/problem-to-solution-template.md. Preserve the two opening tables: the document metadata table first, followed by the Integration Overview table.
13. Run the readability and glossary compliance gate before finishing: