openclaw-skill-ideation

Transform raw brain dumps (dictated freestyle) into structured implementation artifacts. Use when user has messy ideas, scattered thoughts, or dictated strea...

Security Scan

The skill is internally consistent: it transforms messy ideas into specs by reading a project codebase (when present) and writing artifacts under ./docs/ideation/, and it requests no credentials or installs.

Purpose & Capability

The name/description (turn brain dumps into implementation artifacts) aligns with the declared behavior: read the codebase for context, score confidence, ask targeted questions, and write contracts/specs to ./docs/ideation/{project-name}/. No unrelated binaries, env vars, or installs are requested.

Instruction Scope

SKILL.md explicitly instructs the agent to read and search the existing project codebase and to create ./docs/ideation/{project-name}/ and write contract/spec files when confidence ≥95%. Reading the codebase is coherent with the skill's purpose. The instructions do not tell the agent to read unrelated system paths or to send data to external endpoints, but they also do not explicitly limit exploration to a well-defined project root or describe handling of sensitive files (e.g., config files containing secrets).

Install Mechanism

Instruction-only skill with no install spec and no code files. Lowest-risk install surface; nothing will be written to disk by an installer aside from the agent's normal operations when it follows the SKILL.md instructions.

Credentials

The skill requires no environment variables, credentials, or external service access. That matches the described purpose and the instructions.

Persistence & Privilege

always:false (normal). The skill is allowed to be invoked autonomously by the agent (default), and the instructions call for reading the codebase and writing files under ./docs/ideation/. The SKILL.md requires explicit user approval before proceeding from contract generation to spec generation, which limits destructive actions; however, the workflow implies automatic codebase exploration and confidence scoring before that approval step, so the agent may inspect project files as soon as the skill runs. Consider whether autonomous invocation and filesystem access should be restricted by policy.

Assessment

This skill looks coherent and does what it says: it will read your project files to generate contracts and specs and then write them to ./docs/ideation/{project-name}/. Before installing or enabling autonomous invocation: (1) confirm the agent is only allowed to access the intended project directory (not your entire home or system configs), (2) be aware codebase exploration may read files that contain secrets (env files, config, credentials) — if you have such files in the repo, remove or restrict them first, (3) require explicit user approval before letting the skill proceed from contract to spec (the SKILL.md already asks for approval, but enforce it in runtime policy), and (4) review generated files before committing or sharing. If you want extra safety, restrict the skill's filesystem scope to a sandboxed project path and disable autonomous invocation unless you explicitly trigger the skill.

Ideation

Transform unstructured brain dumps into structured, actionable implementation artifacts through a confidence-gated workflow.

Workflow Pipeline

INTAKE → CODEBASE EXPLORATION → CONTRACT FORMATION → PHASING → SPEC GENERATION → HANDOFF
              ↓                        ↓                  ↓            ↓               ↓
         Understand              confidence < 95%?    PRDs or     Repeatable?    Analyze deps
         existing code                ↓               straight      ↓               ↓
                                 ASK QUESTIONS        to specs?   Template +    Sequential?
                                      ↓                           per-phase     Parallel?
                                 (loop until ≥95%)                deltas        

Phase 1: Intake

Accept whatever the user provides:

• Scattered thoughts and half-formed ideas
• Voice dictation transcripts (messy, stream-of-consciousness)
• Bullet points mixed with rambling
• Topic jumping and tangents
• Contradictions and unclear statements
• Technical jargon mixed with vague descriptions

Don't require organization. The mess is the input.

Acknowledge receipt and begin analysis. Do not ask for clarification yet.

Phase 2: Codebase Exploration

Before scoring confidence or generating any artifacts, understand the existing codebase. This is critical — specs written without understanding existing patterns, architecture, and conventions will be generic and wrong.

When to Explore

Exploration is needed when:

• The brain dump references existing code, features, or systems
• The project directory contains source code (not a greenfield project)
• The user mentions extending, modifying, or integrating with existing functionality

Skip exploration for greenfield projects with no existing code.

What to Explore

Use file reading and search to understand:

1. Project structure — What frameworks, languages, and patterns are in use?
2. Relevant existing code — What modules/files relate to the brain dump's scope?
3. Conventions and patterns — How are similar features implemented? What abstractions exist?
4. Testing patterns — How is the codebase tested? What infrastructure exists?
5. Configuration and build — What tools, package managers, and CI/CD are in use?

Do not write exploration findings to files. They're context for the ideation process, not an artifact.

Phase 3: Contract Formation

3.1 Analyze the Brain Dump

Extract from the raw input + codebase exploration:

1. Problem signals: What pain point or need is being described?
2. Goal signals: What does the user want to achieve?
3. Success signals: How will they know it worked?
4. Scope signals: What's included? What's explicitly excluded?
5. Contradictions: Note any conflicting statements
6. Codebase constraints: What does the existing architecture enable or limit?

3.2 Calculate Confidence Score

Score each dimension (0-20 points):

Dimension	Question
Problem Clarity	Do I understand what problem we're solving and why it matters?
Goal Definition	Are the goals specific and measurable?
Success Criteria	Can I write tests or validation steps for "done"?
Scope Boundaries	Do I know what's in and out of scope?
Consistency	Are there contradictions I need resolved?

Total: /100 points

See references/confidence-rubric.md for detailed scoring criteria.

3.3 Confidence Thresholds

Score	Action
< 70	Major gaps. Ask 5+ questions targeting lowest dimensions.
70-84	Moderate gaps. Ask 3-5 targeted questions.
85-94	Minor gaps. Ask 1-2 specific questions.
≥ 95	Ready to generate contract.

3.4 Ask Clarifying Questions

When confidence < 95%, ask clarifying questions:

Question strategy:

• Target the lowest-scoring dimension first
• Be specific, not open-ended
• Offer options when possible ("Is it A, B, or C?")
• Reference what was stated ("You mentioned X, did you mean...?")
• Limit to 3-5 questions per round
• After each round, recalculate confidence

3.5 Generate Contract

When confidence ≥ 95%:

1. Confirm project name with user
2. Convert to kebab-case for directory name
3. Create output directory: ./docs/ideation/{project-name}/
4. Write contract.md using references/contract-template.md
5. Get explicit approval before proceeding

Do not proceed until contract is explicitly approved.

Phase 4: Phasing & Specification

4.1 Choose Workflow

Ask the user:

• Straight to specs — Recommended for technical projects. Faster.
• PRDs then specs — Recommended for large scope or cross-functional teams.

4.2 Determine Phases

Small-project shortcut: If the scope is small enough to implement in a single phase (1-3 components, touches fewer than ~10 files), skip phasing entirely. Generate a single spec.md.

Phasing criteria (for multi-phase projects):

• Dependencies (what must be built first?)
• Risk (tackle high-risk items early)
• Value delivery (can users benefit after each phase?)
• Complexity (balance phases for consistent effort)

4.3 Generate PRDs (if chosen)

For each phase, generate prd-phase-{n}.md using references/prd-template.md.

4.4 Generate Implementation Specs

Generate specs using references/spec-template.md:

• Technical approach
• File changes (new and modified)
• Implementation details with code patterns
• Testing requirements
• Error handling
• Validation commands
• Per-component feedback loops

Reference existing code: Include "Pattern to follow: path/to/similar/file.ts" when relevant patterns exist.

4.5 Present for Review

Before presenting specs, evaluate feedback loop quality. Present all specs for user approval.

Phase 5: Execution Handoff

Present the execution strategy:

Ideation complete. Artifacts written to `./docs/ideation/{project-name}/`.

## To start implementation

Start a fresh session and work through the specs in order:
1. Read the contract for context
2. Read spec-phase-1.md  
3. Implement following the spec
4. Validate using the commands in the spec
5. Commit and move to next phase

Output Artifacts

All artifacts written to ./docs/ideation/{project-name}/:

contract.md                        # Problem, goals, success, scope
prd-phase-1.md                     # Phase 1 requirements (only if PRDs chosen)
spec-phase-1.md                    # Phase 1 implementation spec
spec-template-{pattern}.md         # Shared template for repeatable phases (if applicable)
spec-phase-{n}.md                  # Per-phase specs

Important Notes

• Explore the codebase before scoring confidence (unless greenfield).
• Score confidence conservatively. When uncertain, score lower.
• Never skip the confidence check. Don't assume understanding.
• Always write artifacts to files. Don't just display them.
• Each phase should be independently valuable.
• Specs should be detailed enough to implement without re-reading PRDs or the contract.
• Keep contracts lean. Heavy docs slow iteration.
• Reference existing code patterns in specs.
• Small projects don't need phases. If scope is 1-3 components, generate a single spec.