discover

Discover

Conduct an iterative, expert-driven interview to produce a descriptive brief for any project, program, or activity. The brief must contain enough detail that a future roadmap skill can plan execution without re-interviewing the user.

Checklist

Complete each step in strict order. Do not skip steps. Do not proceed to brief construction (step 10) until the interview is complete and the user confirms they are done (step 8).

Step 1: Determine New vs. Existing Activity

Ask the user if they want to plan a new activity.

• If the user says no: Do not use this skill. Just proceed with the conversation and ask the user how you can help.
• If the user says yes: This is a new activity. Proceed to step 2.

Step 2: Invoke Organize

Ensure the activity directory exists and cd into it first, then invoke do-stuff-helper:organize to bootstrap it with docs, plugins, CLAUDE.md, and a GitHub repo. Confirm the slug and path with the user.

Step 3: Profile Check

Check if the user has a life profile at ~/exoselfai/docs/user-profile.json (use the Read tool; handle file-not-found gracefully).

• If NO profile exists, tell the user:

  "Before we dive in, I notice you don't have a life profile yet. Having one would help me understand how this activity fits into your broader goals. Would you like to build one now, or continue without it?"

  • If yes: invoke do-stuff-helper:user-profile-builder, then return here and continue to step 4.
  • If no: continue to step 4.
• If a profile EXISTS, note it to the user:

  "I can see your life profile — I'll use it to understand how this activity connects to your broader goals." Continue to step 4.

This step is a gentle offer, not a blocker. The discover flow works with or without a profile.

Step 4: Collect Existing Materials

Ask the user if they have any existing materials related to this activity:

• Notes, documents, prior research
• Links, bookmarks, references
• Previous conversations or plans
• Relevant files on their machine

If materials exist, read and incorporate them. If not, acknowledge and move on.

Step 5: Initial Description

Let the user describe the activity in their own words. Do not interrupt or steer — capture their natural framing. Ask a single open-ended question:

"Describe what you want to do and why. Include as much or as little detail as feels right."

Listen actively. Note key themes, goals, constraints, and motivations for use in subsequent steps.

Step 6: Expert Context Analysis

Based on the user's description, determine:

1. Domain(s): What fields or disciplines does this activity span?
2. Expert knowledge: What would a domain expert know that a generalist would not?
3. Expert questions: What would an expert ask to evaluate this activity's feasibility and design?
4. Expert concerns: What risks or pitfalls would an expert worry about?

Do not present this analysis to the user. Use it internally to guide the interview in step 7.

Step 6b: Software-Build Detection

If the user's description is primarily about building a piece of software (an app, API, service, tool, platform, etc.), the brief risks becoming a product spec rather than a project plan. ClaudePluginBuild handles the software spec — the brief should capture everything around the build.

When detected, tell the user:

"It sounds like the core of this project is building a piece of software. When we get to implementation, ClaudePluginBuild will handle the PRD, technical design, and code — so we don't need to specify the software in detail here. Instead, let's make sure we capture the bigger picture: what needs to happen beyond writing the code to make this project successful."

Then steer the remaining interview (Step 7) toward these topics in addition to the standard coverage targets:

• Users and validation — who are the target users, how will you test with real people?
• Deployment and infrastructure — where does it run, how do you ship updates?
• Launch and distribution — how do people find out about it?
• Business model (if applicable) — how does it sustain itself?
• Post-launch — what happens after v1? Maintenance, support, iteration?

The standard coverage targets (goal, scope, risks, etc.) still apply — this step adds topics, it doesn't replace them. The key shift is: the Description section of the brief should describe what the software does at a high level (enough to seed a PRD later), but should not decompose the software architecture, features, or implementation.

When NOT detected (non-software or mixed activities), skip this step entirely.

Step 7: Iterative Expert Interview

Conduct the interview one question at a time. Each question should:

• Draw on the expert context from step 6
• Build on previous answers (do not repeat ground already covered)
• Target a specific aspect of the brief template (goal, scope, success criteria, risks, etc.)
• Be concrete and specific, not generic

Pacing rules:

• Ask ONE question per message
• Wait for the user's response before asking the next question
• Adapt follow-up questions based on what the user reveals
• Research can be invoked at any point during the interview when a topic surfaces that would benefit from investigation — trust your judgment on when research helps

Coverage targets (ensure the interview addresses all of these before moving to step 8):

• Goal and motivation
• Success criteria and how to measure them
• Scope boundaries (what is in, what is out)
• Key risks and mitigation ideas
• Timeline expectations or constraints
• Resource requirements or constraints
• Dependencies on external factors
• Background context that a planner would need

Step 8: Coverage Check

When the interview has covered all targets from step 7, ask the user:

"We've covered [list topics]. Are there other angles or topics you'd like to explore before I draft the brief? Or does this feel complete?"

• If the user raises new topics, return to step 7 and continue the interview.
• If the user confirms they are done, proceed to step 9.

Hard gate: Cannot proceed to step 10 until the user explicitly confirms the interview is complete.

Step 9: Life Goals Connection

If a user profile exists (checked in step 3), use this step to connect the activity to the user's broader life context. If no profile exists, skip to step 10.

Ask the user:

"How does [activity name] relate to your life goals?"

Then ask:

"Does anything in your profile need updating based on this new activity?"

• If updates are needed: note this for step 13, where you will suggest invoking do-stuff-helper:user-profile-builder in update mode after saving the brief.
• If no updates needed: continue to step 10.

Keep this brief — it should feel like a natural checkpoint, not a second interview.

Step 10: Construct the Brief

Draft the brief using the template below. Fill every section with specific, concrete content drawn from the interview. Do not use placeholder text.

# Brief: <Activity Name>

## Goal
What the activity aims to achieve, stated clearly and concisely.

## Why
The motivation — why this matters to the user.

## Success Criteria
Concrete, observable indicators that the activity has succeeded.

## Measurement
How each success criterion will be measured or evaluated.

## Description
What is the end state? What intermediate steps or accomplishments does the user imagine taking on the way. If the activity includes building something, what is that thing and what does it do?

## Scope

### In Scope
What is included in this activity.

### Out of Scope
What is explicitly excluded.

## Key Risks
Identified risks with brief mitigation notes where discussed.

## Open Questions
Unresolved questions that need answers before or during execution.

## Background & Context
Domain knowledge, prior work, constraints, and any other context a planner would need.

## Notes for Roadmap Planning
Timeline expectations, resource constraints, dependencies, phasing suggestions, and anything else relevant to building an execution plan.

Step 11: Self-Review

Before presenting the brief, review it against this checklist:

• Understandable by someone unfamiliar with the conversation
• Success criteria are concrete and observable
• Risks reflect expert-level thinking (not just generic risks)
• Scope boundaries are clear
• Roadmap notes contain enough detail for a planning skill to build an execution plan
• No placeholder or vague language remains
• Open questions are genuine (not things already answered in the interview)

Note any gaps found during self-review for step 12.

Step 12: Final Questions

If the self-review surfaced gaps, ask the user targeted questions to fill them. Keep this round brief — 1-3 questions maximum. Incorporate answers into the brief.

If no gaps were found, skip to step 13.

Step 13: Save and Update CLAUDE.md

1. Save the brief to <activity-dir>/docs/brief-<activity-slug>.md
2. Open <activity-dir>/CLAUDE.md and append an ## Activity Brief section containing:
   • Goal: 1–2 sentence summary of the goal
   • Success Criteria: Bulleted list of the key success criteria
   • Scope: Brief summary of what's in and out of scope
   • Key Risks: Top 2–3 risks
   • A link to the full brief with a note to read it for complete context:

     For full details including background, open questions, and roadmap planning notes, see [the complete brief](docs/brief-<activity-slug>.md).
     

3. Prepend a milestone entry to docs/changelog.md (insert after the # Changelog header, newest first):

   ## YYYY-MM-DD — Activity defined: <Activity Name>
   <1-2 sentence summary of what the brief covers — goals, scope, and key decisions.>
   

4. Stage and commit all changes with message: discover: add brief for <activity-slug>
5. Report the file paths and confirm everything is saved.
6. If step 9 flagged that the user's profile needs updating, suggest it now:

   "You mentioned your profile could use an update. Would you like to do that now before moving on?"

   • If yes: invoke do-stuff-helper:user-profile-builder (it will detect the existing profile and enter update mode), then continue to the roadmap suggestion below.
   • If no: continue to the roadmap suggestion below.
7. Suggest-and-confirm transition to roadmap planning:

   "The brief is saved. The next step is to create a roadmap — an adaptive plan with waypoints, phases, and dependencies. Want to continue to roadmap planning now?"

   • If the user says yes, invoke do-stuff-helper:roadmap
   • If the user says no, acknowledge and end

Cross-Skill Invocation

• do-stuff-helper:organize — Invoke in step 2 for new activities. Bootstraps the activity directory with docs, plugins, CLAUDE.md, and GitHub repo.
• do-stuff-helper:user-profile-builder — Invoke in step 3 if the user wants to build a profile, or in step 13 if they want to update their profile after the interview.
• do-stuff-helper:research — Invoke at any point during the interview (step 7) when a topic surfaces that would benefit from investigation.
• do-stuff-helper:roadmap — Suggest-and-confirm in step 13 after the brief is saved.