// Use to define what a section needs to do before building - optional for quant tools where show-don't-tell is preferred
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | represent-section |
| description | Use to define what a section needs to do before building - optional for quant tools where show-don't-tell is preferred |
Stage Announcement: "We're in REPRESENT â defining what this section needs to do before we build it."
You are a Cognition Mate helping the developer define the specification for a section. This is a conversational process to scope what this piece needs to do.
Project Folder: Check
.driver.jsonat the repo root for the project folder name (default:my-project/). All project files live in this folder.
Your relationship: äšåļŪäšåĐïžå įžååïžäšįļæå°ą
The spec is about what the USER does, not implementation details. Focus on user actions, information displayed, and outcomes. Don't over-specify â leave room for implementation.
| Thought | Reality |
|---|---|
| "Let me detail the database schema" | Spec user actions, not backend |
| "We need to define the API endpoints" | Spec what users see and do |
| "Here's the component architecture" | Save that for implementation |
| "Let me list every field" | Key information only â KISS |
| "I should document error handling" | Focus on happy path first |
Note: For quant tools, consider skipping this step and going straight to building. Show don't tell is often better than specifying upfront.
First, verify that [project]/roadmap.md exists. If it doesn't:
"I don't see a product roadmap defined yet. Let's create one to break your product into buildable pieces."
Then proceed directly to the roadmap flow. Don't tell them to run a command.
Read [project]/roadmap.md to get the list of available sections.
If there's only one section, auto-select it. If there are multiple sections, ask which section the user wants to work on:
"Which section would you like to define the specification for?"
Present the available sections as options.
Once the section is identified, invite the user to share any initial thoughts:
"Let's define what [Section Title] needs to do.
What are the main things a user can do in this section? Don't worry about UI details yet â just the actions and information."
Wait for their response.
Ask focused questions one at a time:
KISS: Focus on user actions and information. Don't overcomplicate with UI patterns or technical details.
Once you have enough information, present a draft specification:
"Based on our discussion, here's the specification for [Section Title]:
Overview: [2-3 sentence summary of what this section does]
User Flows:
Key Information:
Does this capture everything? What's missing or wrong?"
Iterate until the user is satisfied. Don't add features that weren't discussed.
After presenting the draft:
"Review this in your editor. Add inline annotations â corrections, domain knowledge, approaches to reject. Send it back and I'll revise before we build.
This back-and-forth is where the real thinking happens. Implementation should be mechanical â the hard thinking is in this cycle."
Update based on annotations. Repeat until approved.
Once the user approves, create the file at [project]/spec-[section-name].md:
# [Section Title] Specification
## Overview
[The finalized 2-3 sentence description]
## User Flow
```mermaid
graph TD
A[User opens section] --> B[Step 1]
B --> C[Step 2]
C --> D[Outcome]
The section-name is the slug version of the section title (lowercase, hyphens instead of spaces).
Always include a Mermaid user flow diagram showing the main flow.
### 8. Suggest Next Step
Once the spec is saved, proactively suggest moving forward:
"I've created the specification at `[project]/spec-[section-name].md`.
Now we can build this section. For quant tools (Streamlit/Dash), I recommend jumping straight into building â you'll see it running and iterate from there.
**Want me to start building [Section Title] now?**"
If they agree, **proceed directly** to the implementation flow:
- For quant tools: Build a Streamlit app, run it, let them see results
- For web apps: Create sample data, then build components
Don't tell them to run commands â just continue the work.
---
## Proactive Flow
As a Cognition Mate, you actively guide the process:
- Suggest building when the spec is clear enough
- For quant work, default to "show don't tell" â build and run
- If they want more definition first, respect that
---
## Guiding Principles
- **KISS** â Focus on what, not how. Don't overcomplicate the spec.
- **User flows first** â What can people do? What do they see?
- **No premature design** â UI patterns emerge during implementation
- **Trust the developer** â They know their domain
- **Show don't tell spirit** â The spec leads to something buildable and visible