chore: bootstrap skills library — 19 skills + installer + CI auto-tag
Some checks failed
release / tag (push) Has been cancelled
Some checks failed
release / tag (push) Has been cancelled
Phase 1 of mathias/skills extraction (infra#62 Track D — homelab next-step plan addendum). Imports ~/dev/.skills/ verbatim (19 skill dirs + SKILLS_INDEX.md) and adds the installation surface: - Taskfile.yml — install / update / list / release / check targets - install.sh — bootstrap installer for hosts without Task. Idempotent symlink wirer; default checkout at ~/.local/share/skills/ on every host; SKILLS_REF env var pins a tag (default: main). - .gitea/workflows/release.yml — auto-tag every push to main by Bump-Type footer (major/minor/patch, default patch). Skipped when commit contains [skip-release]. - README — usage, versioning, contribution flow, secret-hygiene rule. Phase 1 wires Claude Code only (~/.claude/skills/<name> global + <repo>/.claude/skills/<name> per-repo). Phase 2 adds Crush, opencode, antigravity, and gitea-resident agents (cobalt-dingo, agentsquad) once their skill conventions are researched. Public repo, markdown-only — no secrets, no client names. Verified via pre-push grep before initial push. [skip-release]
This commit is contained in:
Mathias
222
problem-analysis/SKILL.md
Normal file
222
problem-analysis/SKILL.md
Normal file
@@ -0,0 +1,222 @@
|
||||
---
|
||||
name: problem-analysis
|
||||
description: Deeply understand a problem before coding begins. Identify the real problem, stakeholders, constraints, and success criteria. Use before starting any non-trivial feature.
|
||||
---
|
||||
|
||||
# Problem Analysis
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Understand WHAT needs to be solved and WHY — before considering HOW.**
|
||||
|
||||
Premature solution thinking is one of the most expensive mistakes in software. A feature built on a misunderstood problem is waste, no matter how well it's coded.
|
||||
|
||||
> "A problem well-stated is a problem half-solved." — Charles Kettering
|
||||
|
||||
## When to Use
|
||||
|
||||
**Always use before:**
|
||||
- Starting any non-trivial feature (more than a day's work)
|
||||
- Tackling a vague or ambiguous requirement
|
||||
- Making an architectural decision
|
||||
- Starting a new project or significant component
|
||||
|
||||
**When NOT to use:** Bug fixes with clear reproduction steps, one-line changes, configuration updates.
|
||||
|
||||
## The Analysis Process
|
||||
|
||||
### Step 1: Understand the Real Problem
|
||||
|
||||
Don't accept the first statement of a problem at face value. Dig to the real underlying issue.
|
||||
|
||||
**Questions to ask:**
|
||||
- What is the user actually trying to accomplish?
|
||||
- What pain or friction does this create today?
|
||||
- Why is this a problem now? What changed?
|
||||
- What happens if we don't solve it?
|
||||
- Who else is affected?
|
||||
|
||||
**The 5 Whys technique:** Ask "why" five times to reach the root cause.
|
||||
|
||||
```
|
||||
Problem: "The invoice export is too slow"
|
||||
Why? → "Users have to wait 30 seconds"
|
||||
Why? → "We're generating all 5000 invoices in a single query"
|
||||
Why? → "The feature was built for 50 invoices, now there are 5000"
|
||||
Why? → "We didn't anticipate growth"
|
||||
Root: "Batch processing architecture needed, not performance tuning"
|
||||
```
|
||||
|
||||
The solution to "export is slow" might be pagination, async export, or caching — not just query optimization.
|
||||
|
||||
### Step 2: Identify Stakeholders and Their Perspectives
|
||||
|
||||
Every stakeholder has a different view of the problem.
|
||||
|
||||
| Stakeholder | Typical concern |
|
||||
|-------------|----------------|
|
||||
| End user | "I need to accomplish X in Y time" |
|
||||
| Business | "This costs us money / blocks revenue" |
|
||||
| Ops/DevOps | "This creates operational burden" |
|
||||
| Compliance | "This creates regulatory risk" |
|
||||
| Developer | "This is hard to maintain or extend" |
|
||||
|
||||
**Map the stakeholders:** Who is directly affected? Who is indirectly affected? Who has authority over the solution?
|
||||
|
||||
### Step 3: Define User Needs and Pain Points
|
||||
|
||||
Move from "what users say they want" to "what users actually need."
|
||||
|
||||
```
|
||||
User says: "I need a report with 20 columns"
|
||||
User needs: "I need to identify which customers are at risk of churning"
|
||||
|
||||
These may have completely different solutions.
|
||||
```
|
||||
|
||||
**Techniques:**
|
||||
- User journey mapping: walk through the current process step by step
|
||||
- Pain point identification: where is friction, delay, error, confusion?
|
||||
- Job-to-be-done framing: "When [situation], I want to [motivation], so I can [outcome]"
|
||||
|
||||
### Step 4: Clarify Requirements and Constraints
|
||||
|
||||
**Functional requirements:** What must the system do? (In user terms, not technical terms)
|
||||
- "Users can export invoices as PDF"
|
||||
- "The system sends a confirmation email within 5 minutes"
|
||||
|
||||
**Non-functional requirements:** How must the system behave?
|
||||
- Performance: "Export completes in under 5 seconds for 90% of users"
|
||||
- Security: "Only authenticated users can view their own invoices"
|
||||
- Availability: "Export feature available 99.9% of the time"
|
||||
|
||||
**Constraints:** What is fixed and non-negotiable?
|
||||
- Budget/time
|
||||
- Existing systems that must be integrated
|
||||
- Regulatory requirements
|
||||
- Technology choices already made
|
||||
|
||||
### Step 5: Clarify Scope
|
||||
|
||||
Explicitly define what is **in scope** and what is **out of scope**. Out-of-scope items are often as important as in-scope items for preventing scope creep.
|
||||
|
||||
**Template:**
|
||||
```
|
||||
In scope:
|
||||
- [Feature A]
|
||||
- [Feature B]
|
||||
|
||||
Out of scope (for this version):
|
||||
- [Feature C] — will be addressed in v2
|
||||
- [Feature D] — not part of this problem
|
||||
|
||||
Assumptions requiring validation:
|
||||
- [Assumption 1]
|
||||
- [Assumption 2]
|
||||
```
|
||||
|
||||
### Step 6: Define Success Criteria
|
||||
|
||||
Success criteria must be specific and testable. Vague criteria are not criteria.
|
||||
|
||||
```
|
||||
Vague: "Make the dashboard faster"
|
||||
|
||||
Specific and testable:
|
||||
- Dashboard LCP < 2.5s on a 4G connection (measured with Lighthouse)
|
||||
- Initial data load completes in < 500ms (measured from API call to render)
|
||||
- Page is usable within 3s even if non-critical data hasn't loaded
|
||||
```
|
||||
|
||||
**Success criteria format:** `[Metric] [comparison] [threshold] [measurement method]`
|
||||
|
||||
### Step 7: Identify Risks and Unknowns
|
||||
|
||||
| Category | Questions to ask |
|
||||
|----------|-----------------|
|
||||
| Technical | Do we know how to build this? What might surprise us? |
|
||||
| Business | Does the market actually want this? Is the problem real? |
|
||||
| Regulatory | Are there compliance implications? |
|
||||
| Operational | Will this create new operational burden? |
|
||||
| Integration | What external systems does this depend on? |
|
||||
|
||||
## Output: Problem Analysis Document
|
||||
|
||||
The analysis should produce a `problem-analysis.md` document covering:
|
||||
|
||||
```markdown
|
||||
# Problem Analysis: [Feature/System Name]
|
||||
|
||||
## Problem Statement
|
||||
[One paragraph: what problem exists, for whom, and why it matters]
|
||||
|
||||
## Context
|
||||
[How this problem arose, what triggered the need to solve it now]
|
||||
|
||||
## Stakeholders
|
||||
| Stakeholder | Role | Primary concern |
|
||||
|------------|------|----------------|
|
||||
| [Name/role] | [Decision maker/user/affected] | [Their core need] |
|
||||
|
||||
## User Needs and Pain Points
|
||||
- [Pain point 1]: [Specific friction or failure today]
|
||||
- [Pain point 2]: ...
|
||||
|
||||
## Functional Requirements
|
||||
(In user terms, not technical terms)
|
||||
- [ ] [Requirement 1]
|
||||
- [ ] [Requirement 2]
|
||||
|
||||
## Non-Functional Requirements
|
||||
- Performance: [specific, measurable]
|
||||
- Security: [specific]
|
||||
- Availability: [specific]
|
||||
|
||||
## Scope
|
||||
**In scope:** [list]
|
||||
**Out of scope:** [list]
|
||||
|
||||
## Assumptions Requiring Validation
|
||||
- [Assumption 1]: [How to validate]
|
||||
- [Assumption 2]: ...
|
||||
|
||||
## Risks and Unknowns
|
||||
| Risk | Impact | Likelihood | Mitigation |
|
||||
|------|--------|-----------|-----------|
|
||||
| [Risk 1] | High/Med/Low | High/Med/Low | [Strategy] |
|
||||
|
||||
## Success Criteria
|
||||
- [Metric]: [threshold] ([measurement method])
|
||||
- [Metric]: [threshold] ([measurement method])
|
||||
|
||||
## Open Questions
|
||||
- [Question requiring answer before implementation begins]
|
||||
```
|
||||
|
||||
## Mathias Context
|
||||
|
||||
As a digital PM building production software:
|
||||
|
||||
- **Capture the why:** The problem document should capture business context, not just technical requirements. Agents reading it should understand why this matters.
|
||||
- **Think about the user journey:** Walk through the entire experience, not just the feature in isolation.
|
||||
- **Challenge the requirement:** Is this the right problem to solve? Is there a simpler solution?
|
||||
- **Estimate impact:** How many users are affected? How often? What's the cost of not solving it?
|
||||
|
||||
## Transition to Next Steps
|
||||
|
||||
After the problem is understood:
|
||||
|
||||
1. Load `user-stories` skill to decompose into implementable stories
|
||||
2. Load `spec-driven-dev` skill to write a technical specification
|
||||
3. Load `planning` skill to break into tasks
|
||||
|
||||
**Do NOT jump to implementation.** A complete problem analysis prevents the most expensive mistakes.
|
||||
|
||||
## Red Flags — When Analysis Is Incomplete
|
||||
|
||||
- Requirements stated in technical terms ("add an index") instead of user terms ("make search faster")
|
||||
- No clear success criteria ("it should be better")
|
||||
- No stakeholders identified
|
||||
- Assumptions not written down
|
||||
- Scope not defined
|
||||
- "We know what we need to build" — this is usually premature
|
||||
Reference in New Issue
Block a user