Skill: skidvis/openclaw-skill-ideation (version 0.1.0)

--- name: ideation description: Transform raw brain dumps (dictated freestyle) into structured implementation artifacts. Use when user has messy ideas, scattered thoughts, or dictated stream-of-consciousness, or when they want to plan a feature, spec something out, or turn rough ideas into actionable specs. Produces contracts and implementation specs written to ./docs/ideation/{project-name}/. --- # 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.

path: references/confidence-rubric.md
content: # Confidence Assessment Rubric

Use this rubric to score brain dump clarity before generating a contract.

**Threshold**: 95 points minimum to proceed to contract generation.

## Scoring Dimensions

### 1. Problem Clarity (0-20 points)

| Score | Criteria                                                                                    |
| ----- | ------------------------------------------------------------------------------------------- |
| 0-5   | Problem not stated or completely unclear. No idea what we're solving.                       |
| 6-10  | Problem mentioned but vague ("things are slow", "users complain", "it's broken").           |
| 11-15 | Problem clear but missing context: who experiences it, how often, or what impact.           |
| 16-20 | Problem crystal clear: who experiences it, what happens, when it occurs, impact quantified. |

**Questions to ask if low**:
- "What specific problem are you trying to solve?"
- "Who experiences this problem? How often?"
- "What's the cost of not solving this? (time, money, frustration)"
- "Can you describe a specific incident where this was a problem?"

**Examples**:
- Score 5: "The app is bad"
- Score 10: "Users say the app is slow"
- Score 15: "The checkout page loads slowly, causing cart abandonment"
- Score 20: "Checkout page p95 latency is 3.2s, causing 18% cart abandonment, ~$50k/month lost revenue"

---

### 2. Goal Definition (0-20 points)

| Score | Criteria                                                                          |
| ----- | --------------------------------------------------------------------------------- |
| 0-5   | No goals stated. Just a problem or complaint.                                     |
| 6-10  | Vague aspirations ("make it better", "improve UX", "users should like it more").  |
| 11-15 | Goals stated but unmeasurable ("users should be happier", "it should feel fast"). |
| 16-20 | SMART goals with specific metrics ("reduce checkout latency to under 500ms p95"). |

**Questions to ask if low**:
- "What does success look like for this project?"
- "How will you measure whether this worked?"
- "What specific number or metric should change? By how much?"
- "If this project succeeds, what will be different in 3 months?"

---

### 3. Success Criteria (0-20 points)

| Score | Criteria                                                                        |
| ----- | ------------------------------------------------------------------------------- |
| 0-5   | None provided. No way to know when we're done.                                  |
| 6-10  | Subjective criteria only ("looks good", "feels fast", "stakeholder likes it").  |
| 11-15 | Some measurable criteria but incomplete coverage of goals.                      |
| 16-20 | Clear, testable acceptance criteria for ALL stated goals. Pass/fail verifiable. |

**Questions to ask if low**:
- "How will you know when this is done?"
- "What tests would prove this feature works correctly?"
- "What would a QA person check before signing off?"

---

### 4. Scope Boundaries (0-20 points)

| Score | Criteria                                                                                      |
| ----- | --------------------------------------------------------------------------------------------- |
| 0-5   | Unlimited scope. No boundaries stated. Everything could be in scope.                          |
| 6-10  | Some boundaries implied but not explicit. "We're not redesigning everything" type statements. |
| 11-15 | Boundaries stated but gaps exist. Some adjacent features unclear.                             |
| 16-20 | Clear in/out of scope with rationale for exclusions. Future considerations noted.             |

**Questions to ask if low**:
- "What is explicitly NOT part of this project?"
- "Are there related features we should defer to later?"
- "What's the MVP vs. nice-to-have?"
- "If you had to ship in half the time, what would you cut?"

---

### 5. Consistency (0-20 points)

| Score | Criteria                                                           |
| ----- | ------------------------------------------------------------------ |
| 0-5   | Major contradictions in requirements. Impossible to satisfy both.  |
| 6-10  | Some conflicting statements that need resolution.                  |
| 11-15 | Minor inconsistencies that need clarification but aren't blockers. |
| 16-20 | Internally consistent throughout. No contradictions.               |

**Questions to ask if low**:
- "You mentioned [X] but also [Y]. These seem to conflict. Which takes priority?"
- "Earlier you said [A], but now [B]. Can you clarify?"
- "If we can only do one of [X] or [Y], which matters more?"

---

## Confidence Thresholds

| Total Score | Interpretation              | Action                                                                          |
| ----------- | --------------------------- | ------------------------------------------------------------------------------- |
| < 70        | Major gaps in understanding | Ask 5+ questions targeting lowest-scoring dimensions. May need multiple rounds. |
| 70-84       | Moderate gaps               | Ask 3-5 targeted questions. One more round likely sufficient.                   |
| 85-94       | Minor gaps                  | Ask 1-2 specific questions. Almost ready.                                       |
| ≥ 95        | Ready                       | Generate contract. Proceed to phasing and specification.                        |

---

## Question Best Practices

### Do:
- **Be specific**: "What happens when a user tries to bookmark while offline?"
- **Offer options**: "Is offline support A) critical for MVP, B) nice-to-have, or C) future consideration?"
- **Reference context**: "You mentioned 'tags are better than folders.' Should tags be user-created or predefined?"
- **Limit quantity**: 3-5 questions max per round. Don't overwhelm.
- **Prioritize**: Target the lowest-scoring dimension first.

### Don't:
- Ask open-ended questions: "Tell me more" is not useful.
- Ask redundant questions: If they said "mobile app," don't ask "will this be on mobile?"
- Ask leading questions: "You don't want offline mode, right?"
- Ask compound questions: "What's the scope and timeline and who's the user?" is three questions.

---

## Scoring Worksheet

| Dimension        | Score    | Notes |
| ---------------- | -------- | ----- |
| Problem Clarity  | /20      |       |
| Goal Definition  | /20      |       |
| Success Criteria | /20      |       |
| Scope Boundaries | /20      |       |
| Consistency      | /20      |       |
| **TOTAL**        | **/100** |       |

**Lowest dimension**: _________________ (target questions here first)


path: references/contract-template.md
content: # Contract Template

Use this template when generating `contract.md` after reaching ≥95% confidence.

---

# {Project Name} Contract

**Created**: {date}
**Confidence Score**: {score}/100
**Status**: Draft | Approved

## Problem Statement

{1-3 paragraphs describing:
- What pain point exists
- Who experiences it
- Why it matters
- What happens if not solved}

## Goals

{Numbered list of 3-5 specific, measurable goals. Each goal should answer "what does success look like?"}

1. {Goal 1 with measurable outcome}
2. {Goal 2 with measurable outcome}
3. {Goal 3 with measurable outcome}

## Success Criteria

{Bulleted checklist of testable acceptance criteria. These should be verifiable.}

- [ ] {Criterion 1 - specific and testable}
- [ ] {Criterion 2 - specific and testable}
- [ ] {Criterion 3 - specific and testable}
- [ ] {Criterion 4 - specific and testable}

## Scope Boundaries

### In Scope

{Explicit list of what IS included in this project}

- {Feature/capability 1}
- {Feature/capability 2}
- {Feature/capability 3}

### Out of Scope

{Explicit list of what is NOT included, with brief rationale}

- {Excluded item 1} - {why excluded}
- {Excluded item 2} - {why excluded}

### Future Considerations

{Items explicitly deferred to later phases or projects}

- {Deferred item 1}
- {Deferred item 2}

---

_This contract was generated from brain dump input. Review and approve before proceeding to specification._

---

## Template Usage Notes

When filling this template:

1. **Problem Statement**: Be specific about WHO has the problem and WHAT the impact is.

2. **Goals**: Use measurable language. Instead of "improve performance," say "reduce p95 latency from 2s to 500ms."

3. **Success Criteria**: Write as if you're writing test cases. Each criterion should be pass/fail verifiable.

4. **Scope Boundaries**: When in doubt, list it as out of scope. It's easier to add later than to remove.

5. **Future Considerations**: Don't delete good ideas that are out of scope - park them here for later.


path: references/prd-template.md
content: # PRD Template

Use this template when generating `prd-phase-{n}.md` for each implementation phase.

---

# PRD: {Project Name} - Phase {N}

**Contract**: ./contract.md
**Phase**: {N} of {total phases}
**Focus**: {One-line description of this phase's focus}

## Phase Overview

{2-3 paragraphs describing:
- What this phase accomplishes
- Why it's sequenced at this position
- What value users get after this phase completes
- Key dependencies or constraints}

## User Stories

{Numbered user stories for this phase. Format: As a [user type], I want [capability] so that [benefit]}

1. As a {user type}, I want {capability} so that {benefit}
2. As a {user type}, I want {capability} so that {benefit}
3. As a {user type}, I want {capability} so that {benefit}

## Functional Requirements

### {Feature Group 1}

- **FR-{N}.1**: {Requirement description}
- **FR-{N}.2**: {Requirement description}
- **FR-{N}.3**: {Requirement description}

### {Feature Group 2}

- **FR-{N}.4**: {Requirement description}
- **FR-{N}.5**: {Requirement description}

## Non-Functional Requirements

- **NFR-{N}.1**: {Performance requirement - e.g., "API responses under 200ms p95"}
- **NFR-{N}.2**: {Security requirement - e.g., "All user data encrypted at rest"}
- **NFR-{N}.3**: {Accessibility requirement - e.g., "WCAG 2.1 AA compliant"}

## Dependencies

### Prerequisites

{What must be complete before this phase can start}

- {Prerequisite 1 - e.g., "Phase 1 complete"}
- {Prerequisite 2 - e.g., "Database schema deployed"}

### Outputs for Next Phase

{What this phase produces that subsequent phases need}

- {Output 1 - e.g., "User model with authentication"}
- {Output 2 - e.g., "Base API structure"}

## Acceptance Criteria

{Testable criteria that prove this phase is complete}

- [ ] {Criterion 1 - specific and verifiable}
- [ ] {Criterion 2 - specific and verifiable}
- [ ] {Criterion 3 - specific and verifiable}
- [ ] All unit tests passing
- [ ] Integration tests passing
- [ ] No critical bugs open

## Open Questions

{Unresolved items that need answers during implementation. Remove section if none.}

- {Question 1}
- {Question 2}

---

_Review this PRD and provide feedback before spec generation._


path: references/spec-template.md
content: # Spec Template

Use this template when generating `spec-phase-{n}.md` for each approved phase.

---

# Implementation Spec: {Project Name} - Phase {N}

**Contract**: ./contract.md
**PRD**: ./prd-phase-{N}.md *(omit if no PRDs were generated)*
**Estimated Effort**: {T-shirt size: S/M/L/XL}

## Technical Approach

{High-level description of the implementation strategy. 2-3 paragraphs covering:
- Overall architecture approach
- Key technical decisions and rationale
- Patterns or frameworks to use}

## File Changes

### New Files

| File Path               | Purpose                                    |
| ----------------------- | ------------------------------------------ |
| `{path/to/new/file.ts}` | {Brief description of what this file does} |

### Modified Files

| File Path                    | Changes                      |
| ---------------------------- | ---------------------------- |
| `{path/to/existing/file.ts}` | {What to add/change and why} |

## Implementation Details

### {Component/Feature 1}

**Pattern to follow**: `{path/to/similar/implementation.ts}` (if applicable)

**Overview**: {1-2 sentences describing this component}

```typescript
// Key interfaces or types
interface {InterfaceName} {
  {property}: {type};
}

// Key function signatures
function {functionName}({params}): {returnType} {
  // Implementation notes
}
```

**Key decisions**:
- {Decision 1 and rationale}
- {Decision 2 and rationale}

**Implementation steps**:
1. {Step 1}
2. {Step 2}
3. {Step 3}

### {Component/Feature 2}

{Same structure as above}

## Data Model

{If applicable - database schema changes, state shape, etc.}

### Schema Changes

```sql
-- New tables
CREATE TABLE {table_name} (
  id UUID PRIMARY KEY,
  {column} {type},
  created_at TIMESTAMP DEFAULT NOW()
);
```

### State Shape

```typescript
interface {StateName} {
  {property}: {type};
}
```

## API Design

{If applicable - new or modified endpoints}

### New Endpoints

| Method   | Path                  | Description    |
| -------- | --------------------- | -------------- |
| `POST`   | `/api/{resource}`     | {What it does} |
| `GET`    | `/api/{resource}/:id` | {What it does} |

### Request/Response Examples

```typescript
// POST /api/{resource}
// Request
{
  "{field}": "{value}"
}

// Response
{
  "id": "uuid",
  "{field}": "{value}"
}
```

## Testing Requirements

### Unit Tests

| Test File                | Coverage        |
| ------------------------ | --------------- |
| `{path/to/test.spec.ts}` | {What it tests} |

**Key test cases**:
- {Test case 1}
- {Test case 2}
- {Edge case 1}
- {Error case 1}

### Integration Tests

| Test File                       | Coverage        |
| ------------------------------- | --------------- |
| `{path/to/integration.spec.ts}` | {What it tests} |

## Error Handling

| Error Scenario | Handling Strategy                                           |
| -------------- | ----------------------------------------------------------- |
| {Scenario 1}   | {How to handle - e.g., "Return 400 with validation errors"} |
| {Scenario 2}   | {How to handle - e.g., "Retry 3x with exponential backoff"} |

## Validation Commands

```bash
# Type checking
{pnpm run typecheck | npm run typecheck | etc.}

# Linting
{pnpm run lint | npm run lint | etc.}

# Unit tests
{pnpm run test | npm run test | etc.}

# Build
{pnpm run build | npm run build | etc.}
```

## Open Items

{Any remaining questions or decisions to make during implementation. Remove if none.}

- [ ] {Open item 1}
- [ ] {Open item 2}

---

_This spec is ready for implementation. Follow the patterns and validate at each step._


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