Skip to content
Skills Library
Programming · Analysis

analysis

/analysis

Use for unresolved design choices, changed cross-component contracts, material risks, or explicit analysis requests. Known mechanical changes need no analysis; specified multi-step work may still need planning.

Repository
cf-powers ↗
Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use for unresolved design choices, changed cross-component contracts, material risks, or explicit analysis requests. Known mechanical changes need no analysis; specified multi-step work may still need planning.

Original author description

Use for unresolved design choices, changed cross-component contracts, material risks, or explicit analysis requests. Known mechanical changes need no analysis; specified multi-step work may still need planning.

How it works

  1. Overview
  2. Preserve the Intended Outcome
  3. Classify First
  4. The Process
  5. Key Principles
Original SKILL.md headings · 407 lines, 2,755 words
SKILL.md preview
---
name: analysis
description: Use for unresolved design choices, changed cross-component contracts, material risks, or explicit analysis requests. Known mechanical changes need no analysis; specified multi-step work may still need planning.
---

# From Idea to Technical Analysis

**Runtime:** Follow project instructions. Use native skill loading and ordinary
project reads directly. Before dispatch, resume, model selection, or shared plugin
resource resolution, read [runtime operations](../using-superpowers/references/runtime.md)
and the active-host reference once per context. Keep workflow decisions and child runtime constraints unchanged.

## Overview

A single skill that takes you from a vague idea to a reviewed technical analysis document, ready for implementation planning. Combines collaborative dialogue (understanding what to build) with rigorous technical analysis (how to build it).

**Announce at start:** "I'm using the analysis skill to turn this idea into a technical analysis."

**Output:** `docs/plans/YYYY-MM-DD-<topic>.md` — a single document containing both the design rationale and the full technical analysis.

**Output language:** English (document, dialogue, and all skill artifacts). A global
language preference for conversation does not change this. The document follows
[Technical English](../using-superpowers/references/technical-english.md).

## Preserve the Intended Outcome

Apply the Collaboration Defaults from `using-superpowers` in the design dialogue.

Before proposing an approach, identify the intended outcome, who it serves,
and what success looks like from the request and available context. Ask a
focused question only for missing information that would change the design;
do not ask the user to repeat a purpose or constraint they already supplied.

In the selected path's design summary, distinguish the user's requirements
from your assumptions and make them easy to correct. Carry that understanding
into the analysis document when one is needed. Check proposed features against
it so familiarity with an app genre does not substitute for the user's goal.
Use the existing design dialogue for this; it is not another approval stage.

Define the smallest outcome that meets the acceptance criteria. For added complexity,
name its beneficiary, cost, and maintenance owner. Check existing platform capabilities first.
Compare custom work against the actual fit and operating cost of the existing option.
Save effort on speculative generality and polish. Preserve data integrity, secrets,
authorization, necessary recovery, and basic usability. For each deliberate omission,
record why it is safe and what concrete condition would justify revisiting it.

<HARD-GATE>
Before implementation, present the concrete design and obtain approval unless
that same design, scope, and execution choice are already approved in this conversation.
Do not request the same approval again. A general implementation request does not
resolve newly discovered product decisions or compatibility tradeoffs.
An analysis-only request authorizes analysis, not implementation. Keep external
and destructive action authorization separate. These boundaries apply on every path.
</HARD-GATE>

## Classify First

The full analysis document is the right output for a subsystem, not for a flag.
Before your first question, classify the request and **say the classification
out loud** — "this looks bounded, so I'll present a short design in chat rather
than write an analysis document" — so your human partner can override it.

- **Spike** — a feasibility question ("can we…", "is it possible…", "quick and
  dirty is fine") whose output is an answer, not code you keep. Present the
  question and what you'll try in 2-3 sentences, use existing approval or get a nod, then find out as
  cheaply as correctness allows. No analysis document, no plan. Report findings
  as a recommendation; anything you built stays labelled throwaway.

- **Bounded** — a well-scoped change to code that already exists in this repo: a
  new flag, a small endpoint, a one-file fix. Understanding the kind of app is
  not enough — bounded means the flow you are changing is already here to read.
  If there is no existing flow to change, the task is not bounded. Ask the
  clarifying questions that matter, present a short design IN CHAT (a few
  sentences to a few short paragraphs: approach, files touched, testing), and
  obtain approval if this design and scope are not already approved. A bounded
  task retains the same design-approval boundary as an architectural one. No analysis document, no
  plan document; proceed through the normal development workflow (TDD applies).

- **Architectural** — new projects, new subsystems, changes that restructure how
  components fit together or alter interfaces others depend on. Run Phases 1-8
  below in full: dialogue, analysis document, cross-check reviews, then
  cf-powers:writing-plans.

**When in doubt between two paths, take the heavier one.** The ratchet is
one-way: hidden complexity discovered mid-task upgrades the path — stop, say so,
and step up. Nothing downgrades mid-task.

This router governs what happens once the skill is invoked. Whether to invoke it
at all is the description's job: a Dockerfile line, a CI YAML tweak, or a
one-liner the user already specified needs no skill.

### Red Flags

| Thought | Reality |
|---------|---------|
| "This is too simple to need a design" | Once analysis applies, provide a proportionate design and use or obtain approval for it. |
| "I'll call it bounded and skip the analysis" | Reaching for a label to skip work IS the doubt — take the heavier path. |
| "It's bounded and the design is obvious — I'll start while they read it" | The gate is approval of this design. Present it and wait only when that approval is missing. |
| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |
| "The spike works, so I'll keep the code" | Approval to investigate does not authorize retaining production code. |
| "It grew, but I'm almost done — no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. |
| "They approved the spike, so the follow-up change is approved too" | Reuse approval only when the actual design, scope, and execution match. |

## The Process

Phases 1-8 below are the **architectural** path. A spike stops at "present the
probe, use or obtain approval, report". A bounded task uses Phase 1's dialogue and Phase 2's
codebase exploration and presents its short design in chat. It does not enter
Phase 3; continue implementation only within the approval boundary above.

### Phase 1: Understanding the Idea

**Goal:** Understand what we're building and why before writing anything.

**If the user already has a clear spec or design doc** — skip to Phase 2. Not every idea needs 20 questions.

**If the idea is vague or open-ended:**

1. Check out the current project state first (files, docs, recent commits)
2. Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
3. If the project is too large for a single analysis, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then analyze the first sub-project through the normal flow. Each sub-project gets its own analysis → plan → implementation cycle.
4. For appropriately-scoped projects, ask questions **one at a time** to refine the idea
5. Prefer **multiple choice questions** when possible, open-ended is fine too
6. Focus on: purpose, constraints, success criteria, who benefits

**Exploring approaches:**

- When material tradeoffs remain, compare the viable approaches and recommend one.
- When evidence settles the choice, present that path and its reason.
- Honor explicit requests for alternatives. Preserve the existing design approval boundary.

**Validating the design direction:**

- Summarize the outcome, scope, key decision, and unresolved assumptions. Scale detail to the decision; there is no word quota.
- Ask: "Does this capture what you have in mind?"
- Iterate until the user confirms

**Key principles for Phase 1:**
- **One question at a time** — don't overwhelm
- **YAGNI ruthlessly** — remove unnecessary features
- **Explain the choice** — compare real tradeoffs; recommend the established path when the evidence settles the choice

**Design for isolation and clarity:**

- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
- Smaller, well-bounded units are also easier for you to work with — you reason better about code you can hold in context at once, and your edits are more reliable when files are focused.

**Working in existing codebases:**

- Explore the current structure before proposing changes. Follow existing patterns.
- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design — the way a good developer improves code they're working in.
- Don't propose unrelated refactoring. Stay focused on what serves the current goal.

### Phase 2: Codebase Exploration

Before writing anything, thoroughly explore the project:

- Find all files relevant to the proposed changes
- Note specific line numbers for code that will be modified
- Understand existing patterns, data models, and service layers
- Map integration points and dependencies
- Identify what will NOT change (equally important)

### Phase 3: Write the Analysis Document

Write in English with the [Technical English](../using-superpowers/references/technical-english.md) sentence rules. Follow this document structure:

```markdown
# <Topic> — <Short description>

## Overview

What is being built and why.

### Why

- Motivation (bullet points)
- Business value
- Technical debt being addressed

## Current state

How things work today. Include:
- Relevant code paths with file:line references
- Data flow diagrams (ASCII or description)
- Current limitations

| Aspect | Current state | Proposed state |
|--------|---------------|----------------|
| ... | ... | ... |

## Proposed solution

### Architecture

Overall approach. Diagrams where they help.

### Scope decisions

For each deliberate omission, state the omitted capability, why the remaining
outcome is safe and sufficient, and the concrete condition for revisiting it.
Write "None" when there are no deliberate omissions.

### Database changes (if any)

Table definitions with complete DDL:

| Column | Type | Description |
|--------|------|-------------|
| ... | ... | ... |

Migration scripts, seed data.

### Service layer changes

New services, modified services. Method signatures and interfaces only — NO implementation code.
DI registration.

### UI changes (if any)

New views/pages, navigation.

### Configuration

New config values, feature flags.

## Affected files

### New files
- `path/to/file.ext` — description

### Modified files
- `path/to/file.ext:123-145` — what changes and why

### Unchanged files (important)
- `path/to/file.ext` — why no change is needed

## Implementation phases

Logical chunks, NOT micro-tasks (those belong in writing-plans).
Each phase is a coherent unit of work.
**Each phase becomes a separate plan file** in writing-plans.

### Phase 1: <Name>
- What is included
- Expected outcome
- Dependencies on other phases
- [ ] Checklist of main steps

### Phase 2: <Name>
- ...

## Risks and mitigations

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| ... | ... | ... | ... |

## Testing

### Unit tests
- List of test scenarios with expected behavior

### Integration / manual tests
- End-to-end scenarios

### Verification
- Commands to run (build, test suite)
- Grep checks for remaining hardcoded values, etc.

## Notes

Idempotence, edge cases, performance considerations, backward compatibility.

## References

- Links to relevant documentation
- Links to similar implementations in the codebase
```

### Phase 4: Validate Completeness

Before saving, verify the analysis covers all of the following:
- [ ] Problem description with rationale (Overview + Why)
- [ ] Current state analysis with file:line references (Current state)
- [ ] Proposed solution with architecture (Proposed solution)
- [ ] Deliberate omissions, safety rationale, and revisit conditions (Scope decisions)
- [ ] Database changes with full DDL (if applicable)
- [ ] All affected files listed with line references (Affected files)
- [ ] Implementation phases as logical chunks (Implementation phases)
- [ ] Risk analysis table (Risks and mitigations)
- [ ] Testing strategy with specific test cases (Testing)
- [ ] Notes on edge cases and backward compatibility (Notes)

If any section is not applicable, explicitly note "N/A" with a brief reason rather than omitting it.

### Phase 5: Save and Commit

Save the document to `docs/plans/YYYY-MM-DD-<topic>.md`. Commit to git.

### Phase 6: Dispatch Cross-Check Reviews

**REQUIRED:** After saving, dispatch the four review subagents below using the
active runtime. Run them in parallel up to available capacity, queueing the rest.
All use the judgment tier per cf-powers:choosing-subagent-models. Give each child
the absolute runtime reference, role file and review-skill path from this plugin;
role files are `agents/business-analyst-reviewer.md`, `developer-reviewer.md`,
`security-reviewer.md` and `performance-reviewer.md` respectively. Review source
files read-only; write only the assigned review report. The examples below are
dispatch briefs, not a literal tool schema.

**Business Analyst Review:**
```
Reviewer dispatch:
  role: general-purpose
  description: "BA review of analysis"
  prompt: >
    You are a Business Analyst reviewer.
    Read and follow the cf-powers:review-as-ba skill exactly.

    Document to review: docs/plans/YYYY-MM-DD-<topic>.md

    Provide your structured review following the skill's output format.
```

**Developer Review:**
```
Reviewer dispatch:
  role: general-purpose
  description: "Dev review of analysis"
  prompt: >
    You are a Developer reviewer.
    Read and follow the cf-powers:review-as-dev skill exactly.

    Document to review: docs/plans/YYYY-MM-DD-<topic>.md

    Read the actual codebase to verify all claims. Provide your structured review
    following the skill's output format.
```

**Security Review:**
```
Reviewer dispatch:
  role: general-purpose
  description: "Security review of analysis"
  prompt: >
    You are a Security Engineer reviewer.
    Read and follow the cf-powers:review-as-security skill exactly.

    Document to review: docs/plans/YYYY-MM-DD-<topic>.md

    Read the actual codebase to verify security claims. Check applicable project instructions (CLAUDE.md on Claude, AGENTS.md on Codex) for
    project-specific security invariants. Provide your structured review
    following the skill's output format.
```

**Performance Review:**
```
Reviewer dispatch:
  role: general-purpose
  description: "Performance review of analysis"
  prompt: >
    You are a Performance Engineer reviewer.
    Read and follow the cf-powers:review-as-perf skill exactly.

    Document to review: docs/plans/YYYY-MM-DD-<topic>.md

    Read the actual schema, queries, and code to verify performance claims.
    Provide your structured review following the skill's output format.
```

### Phase 7: Incorporate Feedback

After all reviewers return:

1. Present combined feedback to the user
2. Discuss which feedback to incorporate vs. dismiss (with reasoning)
3. Update the analysis document with agreed changes
4. Save the updated version

### Phase 8: Handoff

Continue without the menu only when the user already approved this concrete design,
its scope, and the requested next step. A general "build X" request is not approval
of a design the agent later produced. Present the design and obtain approval before
implementation if that specific approval is missing. Material design changes from
cross-check findings need approval too; editorial corrections do not.
For an analysis-only request, deliver the analysis without implementing it.
Use the menu below when the next step needs the user's choice.

**"Analysis is complete and has passed cross-check review. How would you like to proceed?"**

Options:
- **Create implementation plan** → Invoke `cf-powers:writing-plans`
- **Not yet** — share with team, get additional review, iterate further

## Key Principles

- **Classify before you question** — Announce spike / bounded / architectural first, so your human partner can override the amount of process you're about to spend. Scale the artifact to the task; preserve design approval and reuse it when already supplied.
- **Skip what's not needed** — If the user arrives with a clear spec, skip Phase 1 dialogue and go straight to codebase exploration + analysis.
- **One question at a time** — During Phase 1, never overwhelm with multiple questions.
- **Phases, not micro-tasks** — Analysis groups work into logical phases. Micro-task breakdown belongs in writing-plans.
- **NO implementation code** — Analysis describes WHAT and WHY, not HOW in code. Do not write implementation code, function bodies, or full code blocks. Use only: method signatures, interface definitions, pseudo-code, and short illustrative snippets. Detailed code belongs in the plan phase (writing-plans skill).
- **File:line references** — Every affected file must have specific line references. Vague references are not acceptable.
- **English output** — Use English for artifacts and in-skill dialogue.
- **Cross-check is mandatory on the architectural path** — Once you are writing an analysis document, never skip the BA + Dev + Security + Performance review dispatch. Downgrading to "bounded" to escape the cross-check is the rationalization the Red Flags table names.
- **Verify before writing** — Read the actual code before claiming anything about it. Do not guess file paths or line numbers.
- **YAGNI ruthlessly** — Remove unnecessary features from all designs.

Versions

RepositoryScoreLicence
This page · cloudfieldcz/cf-powers100MIT
oscarks/spectionflow100MIT
matteocervelli/llms100MIT
R-CCS-HPBD/r490Apache-2.0
clawic/skills90MIT

Database snapshot: 13.11.2026 · package version fe478ee57635 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100plan
    On an explicit planning request, always call `read_skill` for this skill before answering. Research first, then return one concise inline plan; do not create a plan file unless the user explicitly asks or a governing workflow requires one. Start and end the reply by saying this…
  • 100planning
    Software implementation planning with optional file-based persistence. Use when asked to plan, when unresolved architecture or scope decisions need a durable record, or when multi-phase implementation needs recovery state. For the full research-and-issue workflow, use the…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.