Skill: shanezzzz/decision-clarity-skill (version 1.0.0)

--- name: decision-clarity description: Improve decision quality by clarifying the real problem, exposing hidden assumptions, reasoning from fundamental facts, reducing unnecessary complexity, and ending with a cleaner recommendation or next step. Use when the user is confused, comparing options, overcomplicating a problem, questioning assumptions, trying to identify the real bottleneck, or asking things like "what am I missing?", "does this really have to be this way?", "what should I remove?", "what is the simplest explanation that still fits?", or "help me think this through". --- # Decision Clarity Use this skill to turn ambiguous, high-value, complexity-prone problems into clearer decisions. This skill combines three reasoning modes in a practical sequence: 1. Socratic questioning to clarify the real issue 2. First-principles thinking to reduce the issue to facts and constraints 3. Occam-style simplification to remove unnecessary complexity Do not use this skill to sound philosophical. Use it to improve judgment. Prefer this skill when the user needs a clearer decision across ambiguity, assumptions, fundamentals, and complexity—not just a single reasoning lens in isolation. ## Core objective Produce answers that: 1. identify the real question 2. expose hidden assumptions 3. reduce the issue to facts, constraints, and causal structure 4. compare options by complexity and assumption load 5. remove false complexity 6. end with a clear recommendation, next step, or test A strong answer should make the user feel: - "the real problem is clearer now" - "you found the assumption I was missing" - "this is simpler than I thought" - "I know what to do next" ## Operating stance Default to clarity before confidence. Ask: - What is the user actually trying to decide or understand? - Which parts of the problem are vague, inherited, or untested? - What facts and hard constraints actually matter? - Which explanation or plan requires fewer unnecessary assumptions? - What is the simplest path that still respects reality? ## Best-fit use cases This skill is especially useful for: - startup and business decisions - product and MVP decisions - content and creator workflow design - operations and process simplification - strategy questions with multiple plausible options - personal decisions where confusion, self-justification, or complexity are distorting judgment - argument and reasoning audits ## Not a good fit for Do not use this skill for: - simple factual lookup - purely mechanical execution tasks - obvious low-stakes choices - cases where the user explicitly wants only conventional guidance without reframing ## Workflow routing Route to the smallest useful workflow. - The problem is vague, overloaded, or poorly framed → `Workflows/Clarify.md` - The issue needs to be broken into facts, constraints, and mechanics → `Workflows/Deconstruct.md` - The issue has too many explanations, steps, features, or moving parts → `Workflows/Simplify.md` - The user needs a recommendation, decision rule, priority order, or test → `Workflows/Decide.md` For non-trivial problems, use the full sequence: 1. Clarify 2. Deconstruct 3. Simplify 4. Decide For simpler problems, compress the sequence but preserve the logic. ## Mode selection Choose the lightest response mode that still improves the decision. ### Mode A: Quick Reframe Use for short questions such as: - "What am I missing?" - "Am I overcomplicating this?" - "Does this really have to be this way?" - "Which option actually makes more sense?" Output: - Real issue - Hidden assumption - Main constraint - Simpler conclusion - Next move ### Mode B: Structured Decision Analysis Use for startup, product, content, operations, and strategic decisions. Output: - Real goal - Assumptions - Basic facts - Hard constraints - Soft constraints - Simpler options - Recommendation - First test or next step ### Mode C: Reasoning Audit Use when the user presents an argument, thesis, or decision path that may be weak, confused, or overbuilt. Output: - Real question - Weak assumptions - Missing evidence or contradiction - Simpler interpretation or design - Refined judgment Do not force a long analysis when a shorter one is enough. ## Required reasoning rules ### 1. Clarify before solving Do not solve the wrong problem well. Restate the issue in outcome terms, not only in the user's current framing. Examples: - "Should I build an app?" may really mean "what is the best delivery mechanism for this user outcome?" - "How do I make this more professional?" may really mean "how do I increase trust, clarity, conversion, or authority?" - "Why is this so hard?" may really mean "which part is actually the bottleneck?" If the question is framed at the wrong level, say so and correct it. ### 2. Surface assumptions explicitly Look for assumptions in: - the user's wording - inherited workflows - industry norms - default best practices - preferred tools or formats - emotional preferences presented as logic Useful prompts to yourself: - What is being treated as necessary? - What would have to be true for this conclusion to hold? - What is being accepted without evidence? - Which assumption is carrying the most weight? ### 3. Reduce the issue to facts and constraints Break the problem into: - goals - user behavior - incentives - cost structure - time requirements - dependencies - information flow - causal drivers - legal or technical boundaries - real risks Prefer mechanism over narrative. Do not say "this is just how the market works" unless you explain the actual mechanics. ### 4. Distinguish hard constraints from soft constraints #### Hard constraints Treat these as real unless evidence suggests otherwise: - physical limits - legal or regulatory limits - hard technical boundaries - fixed budgets or capacities - immovable deadlines already fixed in reality #### Soft constraints Treat these as challengeable by default: - industry conventions - legacy process steps - default tool choices - current org boundaries - aesthetic expectations - existing architecture - "this is how it is usually done" Never present a soft constraint as immutable without justification. ### 5. Prefer lower assumption load When comparing explanations or options, prefer the one that: - requires fewer speculative assumptions - introduces fewer moving parts - adds less coordination cost - preserves the real goal with less structure - still adequately fits the facts and constraints Do not simplify by deleting reality. Simplicity must remain sufficient. ### 6. End with a decision Always end with one of: - a recommendation - a decision rule - a priority order - a smallest useful experiment - a first implementation step - a short list of what to answer next Do not end with abstract reflection alone. ## If information is incomplete Do not stall. Instead: 1. name the key ambiguity 2. state the most likely interpretations 3. make the minimum necessary assumptions explicit 4. proceed with the best current interpretation 5. say what fact would most change the recommendation ## Domain references Read only the relevant references when useful: - `references/business.md` for startup, pricing, growth, distribution, and strategy - `references/product.md` for MVP, feature decisions, onboarding, user jobs, and scope - `references/content.md` for tutorials, creator workflows, content quality, and production systems - `references/operations.md` for SOPs, approvals, handoffs, and workflow simplification - `references/trigger-questions.md` for transforming vague user prompts into sharper analysis frames - `references/output-patterns.md` for stable response structure - `references/examples.md` for concrete high-value examples - `references/anti-patterns.md` whenever the reasoning risks becoming overly abstract, endlessly inquisitive, falsely simple, or non-actionable ## Quality bar A strong answer produced with this skill should: - identify the real decision or question - expose the hidden assumption - separate facts from inertia - reduce unnecessary complexity - preserve adequacy - leave the user with a cleaner next step If the answer sounds clever but does not improve the user's decision quality, it is not good enough.

path: README.md
content: # decision-clarity

A reusable agent skill for improving decision quality in ambiguous, high-value, complexity-prone problems.

This skill helps an LLM clarify the real question, expose hidden assumptions, reason from fundamental facts, reduce unnecessary complexity, and end with a cleaner recommendation or next step.

It combines three complementary reasoning modes in a practical sequence:

1. **Socratic questioning** to clarify the real issue
2. **First-principles thinking** to reduce the issue to facts and constraints
3. **Occam-style simplification** to remove unnecessary complexity

## What this skill does

This skill is designed to help agents:

- identify the real decision or question
- expose hidden assumptions
- separate facts from inertia and convention
- reduce problems into constraints, mechanisms, and causal structure
- compare options by complexity and assumption load
- remove false complexity without deleting reality
- end with a recommendation, next move, or test

## Best use cases

Use this skill when the user asks things like:

- What am I missing?
- Does this really have to be this way?
- What should I remove?
- What is the simplest explanation that still fits?
- Help me think this through.
- Which option actually makes the most sense?

It is especially useful for:

- startup and business decisions
- product and MVP decisions
- content and creator workflow design
- operations and process simplification
- strategy questions with multiple plausible options
- personal decisions distorted by confusion, self-justification, or excess complexity
- argument and reasoning audits

## Structure

```text
decision-clarity/
├── SKILL.md
├── Workflows/
│   ├── Clarify.md
│   ├── Deconstruct.md
│   ├── Simplify.md
│   └── Decide.md
└── references/
    ├── anti-patterns.md
    ├── business.md
    ├── content.md
    ├── examples.md
    ├── operations.md
    ├── output-patterns.md
    ├── product.md
    └── trigger-questions.md
```

## Workflow model

### 1. Clarify
Identify the real question, clean up vague framing, and expose initial assumptions.

### 2. Deconstruct
Reduce the problem into facts, constraints, mechanisms, and causal structure.

### 3. Simplify
Remove unnecessary complexity and compare options by assumption load while preserving adequacy.

### 4. Decide
Convert the clarified, decomposed, and simplified reasoning into a practical recommendation, next move, or test.

## Included references

- **anti-patterns.md** — failure modes such as endless inquiry, false simplicity, and analysis without action
- **business.md** — startup, pricing, growth, distribution, and strategy questions
- **product.md** — MVP, feature decisions, onboarding, and scope simplification
- **content.md** — tutorials, creator workflows, and audience-value decisions
- **operations.md** — SOPs, approvals, handoffs, and process simplification
- **trigger-questions.md** — transforms vague prompts into sharper analysis frames
- **output-patterns.md** — structured response formats
- **examples.md** — concrete examples of full decision-clarity reasoning in action

## Install

Install from GitHub with the Skills CLI:

```bash
npx skills add shanezzzz/decision-clarity-skill
```

You can also inspect the package before installing:

```bash
npx skills add shanezzzz/decision-clarity-skill --list
```

## Design goals

This skill is meant to be both:

- a directly usable end-user skill for high-quality decision support
- a reusable reasoning primitive for other decision-oriented skills

The goal is not to produce deeper-sounding analysis. The goal is to produce clearer decisions and better next steps.


path: references/examples.md
content: # Examples

Use these examples to recognize the full decision-clarity sequence.

Pattern:

- Surface question
- Real issue
- Assumptions
- Facts and constraints
- Simplified options
- Best current move

## Example 1: Startup idea confusion

### Surface question
Is this a good startup idea?

### Real issue
Is there a painful enough problem, for a clear enough buyer, with economics that could work?

### Assumptions
- the market is big enough
- users care enough
- the current alternatives are weak
- more features will improve competitiveness

### Facts and constraints
- pain level and urgency matter more than narrative quality
- switching costs may be high
- buyer trust may be the bottleneck
- limited resources force prioritization

### Simplified options
- broad product for many users
- narrow product for one painful job

### Best current move
Test the narrowest painful job first with a simple value promise.

---

## Example 2: Overbuilt MVP

### Surface question
What should we include in the MVP?

### Real issue
What is the smallest product that can create a meaningful result and produce evidence of demand?

### Assumptions
- users expect breadth
- competitor parity matters immediately
- missing secondary features will kill adoption

### Facts and constraints
- the core promised outcome must work
- resources are limited
- extra features increase confusion and development drag

### Simplified options
- multi-feature launch
- narrow outcome-first launch

### Best current move
Ship the smallest version that solves one painful outcome clearly and measure activation plus repeat usage.

---

## Example 3: Heavy content workflow

### Surface question
Why does making tutorials take so long?

### Real issue
Which parts of the workflow create audience value, and which parts only create production drag?

### Assumptions
- high effort equals high quality
- each tutorial needs a unique process
- heavy editing is necessary

### Facts and constraints
- correctness and clarity matter
- proof and pacing matter
- much polish does not materially improve understanding

### Simplified options
- full custom production each time
- repeatable pipeline with reuse

### Best current move
Create one reusable tutorial pipeline and compare production time against audience response.

---

## Example 4: Bloated workflow

### Surface question
Why is this process so slow?

### Real issue
Which steps are real risk controls, and which are inherited organizational friction?

### Assumptions
- each approval is necessary
- more oversight always reduces risk
- current sequencing is safest

### Facts and constraints
- some steps exist only because of old incidents
- handoffs increase cycle time
- only some approvals are tied to real risk

### Simplified options
- keep full workflow
- remove duplicate approvals and merge low-value handoffs

### Best current move
Simplify one low-risk version of the process and compare cycle time plus error rate.


path: references/product.md
content: # Product

Use this file for feature prioritization, MVP scope, onboarding, user-job analysis, and product simplification.

## Core orientation

Most product confusion comes from mixing these layers:

- user outcome
- workflow
- interface
- feature
- implementation

Do not assume the requested feature is the real solution.

## Key lenses

Examine:

- user job
- current friction
- desired outcome
- minimum capability
- feature assumption load
- complexity added by each layer
- time-to-value

## Strong questions

- What user outcome is actually blocked?
- Is this feature the smallest intervention that solves it?
- Are we building this because users need it, or because the product is unfocused elsewhere?
- What can be removed while preserving the core result?
- What is the smallest product shape that still creates real value?

## Typical outputs

- tighter MVP scope
- fewer compensatory features
- clearer product focus
- simpler onboarding path
- better now-vs-later sequencing


path: references/operations.md
content: # Operations

Use this file for workflows, SOPs, approvals, handoffs, internal processes, and efficiency redesign.

## Core orientation

Most operational heaviness comes from:

- inherited approvals
- team-boundary friction
- duplicate information entry
- meetings compensating for poor information flow
- outdated process patches that were never revisited

## Key lenses

Examine:

- desired outcome
- trigger
- transformations
- approvals
- handoffs
- control points
- failure modes
- monitoring needs

## Strong questions

- If this process were designed today, would it still look like this?
- Which steps create value, and which steps only manage history or anxiety?
- What truly requires human review?
- Which handoffs are caused by org design rather than task logic?
- What step can be removed first without unacceptable risk?

## Typical outputs

- fewer steps
- fewer handoffs
- less approval drag
- simpler process design
- lower coordination cost


path: references/business.md
content: # Business

Use this file for startup, pricing, growth, positioning, distribution, moat, and strategic choice questions.

## Core orientation

Most business confusion comes from one of these:

- the problem is not painful enough
- the buyer is not clearly defined
- value is not expressed cleanly
- distribution is weak
- retention is weak
- pricing does not match value mechanics
- the business has become more complex than necessary

## Key lenses

Examine:

- problem pain
- urgency
- willingness to pay
- trust
- switching friction
- distribution mechanics
- activation
- retention
- monetization
- defensibility

## Strong questions

- What must be true for this business to work?
- What is the real basis of competition here?
- What are we assuming about the customer?
- Is pricing copied from the market instead of derived from value?
- Which variable most determines survival right now?

## Typical outputs

- cleaner go-to-market path
- simpler business model
- narrower target customer
- more realistic moat interpretation
- first experiment instead of full strategy theater


path: references/content.md
content: # Content

Use this file for tutorial systems, creator workflows, content quality, publishing processes, and audience-value decisions.

## Core orientation

Most content complexity comes from confusing:

- production effort with audience value
- polish with clarity
- creator standards with user outcomes
- format habits with actual learning needs

## Key lenses

Examine:

- audience outcome
- clarity
- proof
- trust
- density
- production load
- repeatability
- reuse
- distribution fit

## Strong questions

- What should the viewer understand, believe, or do by the end?
- Which production steps improve that outcome?
- Which steps mainly serve creator identity or aesthetics?
- What is the simplest repeatable content system that still feels high-value?
- Can one core artifact produce multiple outputs?

## Typical outputs

- simpler production pipeline
- better value definition for content quality
- reduced vanity complexity
- clearer content format decisions
- stronger reuse and leverage


path: references/trigger-questions.md
content: # Trigger Questions

Use this file to translate vague user prompts into sharper analysis frames.

## Surface question
"Should I build an app?"

## Sharper frame
- What user outcome must be delivered?
- Is an app necessary, or just one candidate delivery mechanism?
- What is the smallest format that could prove adoption?

---

## Surface question
"How do I make this more professional?"

## Sharper frame
- Professional in what sense: trust, clarity, conversion, authority, or price justification?
- Which visible or structural elements actually create that effect?
- Which polish steps are inherited aesthetics rather than outcome drivers?

---

## Surface question
"Why is this so complicated?"

## Sharper frame
- Which part is actually complex?
- Which complexity is real?
- Which complexity is inherited from process, tool, or expectation?
- What would a simpler but still adequate version look like?

---

## Surface question
"What am I missing?"

## Sharper frame
- What assumption is most likely hidden?
- What term is still vague?
- What evidence is missing?
- What simpler interpretation already fits the facts?

---

## Surface question
"Which option makes the most sense?"

## Sharper frame
- What decision are we actually making?
- What criteria matter most?
- Which option requires fewer assumptions while still achieving the goal?
- What is the best current move, not the perfect move?

---

## Surface question
"How do I make better content?"

## Sharper frame
- Better in what dimension?
- What user outcome matters most?
- Which production steps improve that outcome?
- What complexity can be removed without losing value?


path: references/anti-patterns.md
content: # Anti-Patterns

Use this file to avoid turning decision clarity into abstract, bloated, or misleading reasoning.

## Core warning

This skill should not become:

- endless questioning
- contrarian theater
- empty abstraction
- false simplicity
- analysis without action
- "it depends" used as an escape

The goal is better judgment, not more intellectual performance.

## Common failure modes

### 1. Endless inquiry

Bad pattern:
Asking many questions without improving understanding.

Correction:
Ask only the questions that change the decision or clarify the problem.

### 2. Solving the wrong question well

Bad pattern:
Accepting the user's framing without checking whether it is the real issue.

Correction:
Clarify the actual goal before analyzing solutions.

### 3. Abstract decomposition

Bad pattern:
Talking about fundamentals without naming actual facts, constraints, costs, incentives, or mechanisms.

Correction:
Reduce the problem into concrete parts.

### 4. False simplicity

Bad pattern:
Removing complexity by ignoring important evidence or constraints.

Correction:
Simplicity must preserve adequacy.

### 5. Contrarian posturing

Bad pattern:
Rejecting norms automatically because they are conventional.

Correction:
Reject only what fails decomposition or necessity.

### 6. No recommendation

Bad pattern:
The answer is insightful but leaves the user with no clearer move.

Correction:
Always end with a recommendation, next step, or decision rule.

### 7. Overbuilding the answer

Bad pattern:
The analysis becomes more complex than the problem.

Correction:
Use the lightest structure that still improves the decision.

## Self-check before finalizing

Ask:

- Did I identify the real question?
- Did I expose the main assumption?
- Did I separate facts from inertia?
- Did I simplify without deleting reality?
- Did I end with a useful next move?

If any answer is no, revise.


path: references/output-patterns.md
content: # Output Patterns

Use these patterns when a structured answer improves clarity.

## Pattern 1: Quick reframe

- Real issue
- Hidden assumption
- Main constraint
- Simpler conclusion
- Next move

## Pattern 2: Structured decision analysis

- Real goal
- Assumptions
- Basic facts
- Hard constraints
- Soft constraints
- Simplified options
- Recommendation
- First test

## Pattern 3: Reasoning audit

- Real question
- Weak assumptions
- Missing evidence or contradiction
- Simpler interpretation
- Refined judgment
- Next checkpoint

## Pattern 4: Product or business choice

- Real decision
- Current assumptions
- Facts that matter
- Complexity drivers
- Better options
- Best current move

## Pattern 5: Workflow simplification

- Desired outcome
- Existing complexity
- What is essential
- What can be removed
- Simplified design
- First removal or test


path: Workflows/Decide.md
content: # Decide Workflow

Use this workflow to convert clarified, decomposed, and simplified reasoning into a practical judgment or next move.

## When to use

Use this workflow when:

- the user needs a recommendation
- multiple options remain
- the issue is clearer but still unresolved
- analysis must become action
- the conversation risks ending in abstract reflection

## Core question

Given the clarified problem, real facts, and simplified options, what is the best current move?

## Process

### Step 1: Keep only what survived scrutiny

Retain only:

- the real goal
- supported facts
- hard constraints
- lower-assumption options
- relevant tradeoffs

### Step 2: Remove what did not survive

Discard:

- vague framing
- unsupported assumptions
- inherited but challengeable defaults
- complexity without clear value
- weak options that only look complete

### Step 3: State the best current judgment

Produce one of:

- a recommendation
- a priority order
- a preferred option
- a decision rule
- a cleaner framing of the remaining choice

### Step 4: Name the main tradeoff or risk

Be explicit about what is being sacrificed, accepted, or still uncertain.

### Step 5: End with an immediate next move

Give:

- a first action
- a smallest useful experiment
- a validation step
- a question that must be answered next

## Output format

- What is now clear
- What still matters
- Best current recommendation
- Main tradeoff or risk
- Next move

## Quality bar

A good decision output should feel more decisive, more grounded, and more usable than the original discussion.


path: Workflows/Clarify.md
content: # Clarify Workflow

Use this workflow to identify the real question before trying to solve it.

## When to use

Use this workflow when:

- the user's question is vague
- key terms are undefined
- the user is mixing goal and method
- a tactical question is hiding a strategic one
- the problem is emotionally charged or poorly framed
- the issue cannot be examined because nothing has been defined cleanly

## Core question

What is the user actually trying to decide, understand, or achieve?

## Process

### Step 1: Restate the surface question

Write the question as the user currently frames it.

### Step 2: Identify vague or overloaded language

Look for terms such as:

- better
- professional
- scalable
- necessary
- good
- worth it
- risky
- simple
- successful
- high quality

Ask what each one means in this specific context.

### Step 3: Separate goal from method

Check whether the user is naming:

- the real outcome
- a preferred method
- a fear
- a constraint
- a proxy metric
- a social expectation

Do not assume the user's preferred method is the real objective.

### Step 4: Surface initial assumptions

Identify the first layer of hidden assumptions in the framing.

Examples:
- an app is necessary
- more complexity means more quality
- competitors define the right structure
- the bottleneck is already known

### Step 5: Rewrite the problem cleanly

State the sharpest version of the actual question.

## Output format

- Surface question
- Ambiguous terms
- Hidden assumptions
- Real goal
- Reframed question

## Quality bar

A good clarification should make the problem narrower, more precise, and easier to evaluate.


path: Workflows/Simplify.md
content: # Simplify Workflow

Use this workflow to reduce unnecessary complexity while preserving adequacy.

## When to use

Use this workflow when:

- there are too many options
- the proposed solution feels overbuilt
- the explanation has too many assumptions
- the workflow contains too many steps
- the system has too many moving parts
- the user asks what can be removed

## Core question

What is the simplest path, explanation, or design that still works?

## Process

### Step 1: Define adequacy

State the minimum thing the explanation or system must do.

Do not simplify before defining what must be preserved.

### Step 2: List current options or moving parts

Make the competing explanations, features, steps, or structures explicit.

### Step 3: Measure assumption load

For each option or component, ask:

- how many extra assumptions it requires
- how many dependencies it adds
- how many actors or handoffs it introduces
- whether it exists for a real function or just for reassurance
- whether it is compensating for another weak part of the system

### Step 4: Remove non-essential complexity

Prefer removing:

- decorative complexity
- speculative additions
- duplicate layers
- workaround-driven structure
- optional steps with low payoff

### Step 5: Compare simplified candidates

Prefer the option that:

- still fits the facts
- still satisfies the real goal
- uses fewer assumptions
- adds less coordination cost
- is easier to test or execute

### Step 6: State what would force more complexity

Name the evidence or condition that would justify a more complex model or design later.

## Output format

- What must be preserved
- Current options or moving parts
- Assumption load
- What can be removed
- Simplest sufficient option
- What would justify more complexity later

## Quality bar

A good simplification should feel cleaner and more direct without becoming naive.


path: Workflows/Deconstruct.md
content: # Deconstruct Workflow

Use this workflow to reduce a problem into basic facts, constraints, mechanics, and causal structure.

## When to use

Use this workflow when:

- the issue feels large or fuzzy
- a problem is being treated as a black box
- cost, difficulty, or slowness is being accepted without decomposition
- a decision depends on understanding the real mechanism
- the current framing may be inherited from habit or industry convention

## Core question

What is this problem actually made of?

## Process

### Step 1: State the real goal

Write the actual outcome that matters.

### Step 2: Break the issue into constituent parts

Reduce the problem into components such as:

- users
- tasks
- costs
- steps
- incentives
- dependencies
- time requirements
- decision points
- risks
- constraints

### Step 3: Identify basic facts

List only what is currently supported by evidence, observation, logic, or hard boundaries.

### Step 4: Classify constraints

Separate:

- hard constraints
- soft constraints
- open assumptions

### Step 5: Map causal structure

Explain what seems to be causing what.

Examples:
- why a workflow is slow
- why growth is expensive
- why the product feels bloated
- why the user is confused

### Step 6: Highlight false complexity

Show where the default story is larger or more mystical than the actual structure.

## Output format

- Real goal
- Problem components
- Basic facts
- Hard constraints
- Soft constraints
- Causal structure
- False complexity or misleading framing

## Quality bar

A good deconstruction should make the issue feel more concrete, more measurable, and less inherited.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)