claude: added task refinement skill

tools/scopy_dev_plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "scopy_dev_plugin",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Scopy development tools: code generation, documentation, testing, quality checks, and styling for IIO plugin development.",
   "author": { "name": "Muthi Ionut Adrian" }
 }

tools/scopy_dev_plugin/README.md

@@ -29,13 +29,41 @@ Both must be on your `PATH`. On Ubuntu: `sudo apt install clang-format` and `pip
 
 ## Slash Commands
 
+### Task Refinement Pipeline
+
+Turn vague development ideas into concrete, actionable designs. These two commands form a pipeline — use `/clarify-task` to refine a vague idea, then `/design-task` to produce a full design document. Each command is independently usable.
+
+| Command | Description |
+|---------|-------------|
+| `/scopy_dev_plugin:clarify-task <vague idea>` | Ask clarifying questions, explore code, produce a structured task brief |
+| `/scopy_dev_plugin:design-task <refined task>` | Analyze architecture, propose approaches, produce a full design document |
+
+**Recommended model:** Opus — both commands perform deep codebase exploration and complex architectural reasoning.
+
+**Example workflow:**
+```
+/scopy_dev_plugin:clarify-task add spectrum analyzer to ADC plugin
+  → answers questions, explores code → task brief
+
+/scopy_dev_plugin:design-task <paste or reference the task brief>
+  → proposes 2-3 approaches → detailed design doc
+  → optionally saved to docs/design/
+```
+
+### Code Generation & Documentation
+
 | Command | Description |
 |---------|-------------|
 | `/scopy_dev_plugin:create-api <plugin>` | Generate JavaScript API class for test automation |
 | `/scopy_dev_plugin:create-docs <plugin>` | Generate RST plugin user-guide documentation |
 | `/scopy_dev_plugin:create-test-docs <plugin>` | Generate RST test case documentation |
 | `/scopy_dev_plugin:create-automated-tests <plugin>` | Create JS automated test scripts |
 | `/scopy_dev_plugin:create-whatsnew <plugin> <version>` | Generate What's New HTML page |
+
+### Quality & Validation
+
+| Command | Description |
+|---------|-------------|
 | `/scopy_dev_plugin:check-code-quality <package>` | Static code quality analysis |
 | `/scopy_dev_plugin:verify-package <package>` | CI pre-flight validation (format + license) |
 | `/scopy_dev_plugin:validate-api <plugin>` | Validate API class implementation (checks A1–A7) |
@@ -45,12 +73,22 @@ Both must be on your `PATH`. On Ubuntu: `sudo apt install clang-format` and `pip
 
 These skills are loaded automatically when relevant context is detected:
 
+### Plugin Development
 - **iiowidget-patterns** — How to create IIOWidgets using IIOWidgetBuilder
 - **scopy-style-rules** — Theme system, Style::setStyle, background colors
 - **scopy-plugin-patterns** — Plugin lifecycle, ToolTemplate, refresh buttons
+- **scopy-api-patterns** — API class structure and Q_INVOKABLE patterns
+
+### Documentation & Testing
 - **scopy-doc-format** — RST documentation conventions
 - **scopy-test-format** — Test case UID and RBP conventions
-- **scopy-api-patterns** — API class structure and Q_INVOKABLE patterns
+
+### Task Refinement (loaded by clarify-task and design-task commands)
+- **scopy-architecture-knowledge** — Plugin lifecycle, library dependencies, build system, key design patterns
+- **scopy-tools-inventory** — Catalog of all dev tools (package generator, CI, testing, format scripts)
+- **scopy-component-relationships** — Library dependency graph, plugin families, style system, build flags
+- **scopy-decision-frameworks** — Decision trees for plugin vs core, widget type, sync vs async, API exposure
+- **external-research** — Guidelines for researching external solutions (Context7, ADI docs, web search)
 
 ## Hooks
 

tools/scopy_dev_plugin/commands/clarify-task.md

@@ -0,0 +1,125 @@
+# /clarify-task — Refine a vague Scopy development task into a structured task brief
+
+> **Recommended model:** Opus — this command performs deep codebase exploration and multi-step reasoning to produce high-quality task briefs.
+
+You are helping the user turn a vague or incomplete development idea into a concrete, actionable task brief for the Scopy project.
+
+**Raw task description:** `$ARGUMENTS`
+
+## Step 0: Load context
+
+Load these knowledge skills by reading their SKILL.md files:
+- `scopy-architecture-knowledge` — core architecture patterns
+- `scopy-component-relationships` — how components interact
+- `scopy-decision-frameworks` — architectural decision trees
+- `external-research` — guidelines for researching external solutions
+
+## Step 1: Initial analysis
+
+Classify the task into one or more categories:
+- **New plugin/package** — creating something from scratch
+- **Modification to existing plugin** — changing existing functionality
+- **Core infrastructure change** — modifying shared libraries
+- **Tooling/CI change** — build system, scripts, CI pipelines
+- **Documentation** — docs, tests, guides
+- **Cross-cutting concern** — affects multiple modules
+
+Based on classification, identify which Scopy modules/packages are likely involved:
+- Use the Glob tool to find relevant source files and headers
+- Use the Grep tool to search for related patterns, class names, or keywords
+- Read key files (plugin headers, tool classes, CMakeLists.txt) to understand current state
+
+If the task mentions external technologies, unfamiliar concepts, or problems that might have existing solutions outside Scopy:
+- Use web search or Context7 to gather context
+- Check `https://analogdevicesinc.github.io` for ADI hardware/driver documentation
+- Note findings for inclusion in the task brief
+
+## Step 2: Clarifying questions
+
+Ask **3-6 clarifying questions**, one at a time, using the AskUserQuestion tool. Each question should be informed by what you learned from code exploration.
+
+**Question categories (use as needed, not a fixed script):**
+
+1. **Scope** — "What exactly should change? What should NOT change?"
+   - Informed by: what you found in the code (e.g., "I see the ADC plugin has 3 tools — are we adding to an existing tool or creating a new one?")
+
+2. **Users** — "Who uses this feature?"
+   - Options: end user (Scopy GUI), developer (code/API), tester (automation), CI system
+
+3. **Constraints** — "Are there hardware requirements, platform considerations, or performance needs?"
+   - Informed by: device compatibility, IIO attributes available, cross-platform concerns
+
+4. **Integration** — "How does this interact with existing plugins/tools?"
+   - Informed by: MessageBroker topics, shared widgets, library dependencies
+
+5. **Success criteria** — "How do we know it's done? What does 'working' look like?"
+   - Help the user define concrete acceptance criteria
+
+6. **Priority/timeline** — "Is this blocking something? What's the urgency?"
+
+**Guidelines:**
+- Prefer multiple-choice questions (use AskUserQuestion options) when possible
+- One question per message — do not combine questions
+- Adapt based on previous answers — skip irrelevant categories
+- Reference specific code/files you found during exploration to make questions concrete
+
+## Step 3: Deep exploration
+
+After all questions are answered, do a final targeted code exploration:
+- Read relevant plugin/library source files identified during Q&A
+- Identify existing patterns, utilities, or widgets that can be reused
+- Find similar implementations in other plugins (cross-reference)
+- Search externally if the task requires technology or patterns not in the codebase
+- Note any potential conflicts or dependencies
+
+## Step 4: Generate task brief
+
+Present the following structured task brief in the conversation:
+
+```markdown
+## Task Brief: <descriptive title>
+
+**Type:** <new feature | modification | infrastructure | tooling | documentation | cross-cutting>
+**Modules affected:** <list of packages/libraries>
+**Summary:** <2-3 sentence refined description of what needs to be done>
+
+### Requirements
+- <concrete, testable requirement 1>
+- <concrete, testable requirement 2>
+- ...
+
+### Existing Resources
+- <file/pattern/utility> — <why it's useful for this task>
+- ...
+
+### External Resources (if applicable)
+- <library/doc/pattern found via research> — <relevance>
+- ...
+
+### Key Decisions Made
+- <decision from Q&A with rationale>
+- ...
+
+### Open Questions (if any)
+- <things that still need resolution before design>
+
+### Suggested Next Step
+> Run `/scopy_dev_plugin:design-task` with this brief to generate a full design document with architectural choices, component design, and testing strategy.
+```
+
+## Step 5: Save (optional)
+
+Ask the user if they want to save the task brief:
+
+> "Would you like me to save this task brief to `docs/design/YYYY-MM-DD-<topic>-brief.md`?"
+
+If yes, write the file. Do NOT commit — let the user decide when to commit.
+
+## Rules
+
+- Do NOT write any code or modify source files — this command produces only a task brief
+- Do NOT skip the clarifying questions phase — even if the task seems clear, validate with the user
+- Do NOT ask more than 6 questions — consolidate if needed
+- Always explore the codebase before asking questions — informed questions are better questions
+- Always check for external solutions when the task involves unfamiliar technology
+- Reference specific files and line numbers when discussing existing code

tools/scopy_dev_plugin/commands/design-task.md

@@ -0,0 +1,193 @@
+# /design-task — Generate an architectural design document for a Scopy development task
+
+> **Recommended model:** Opus — this command performs complex architectural reasoning and produces detailed design documents.
+
+You are creating a detailed design document for a Scopy development task. The input may be a refined task brief (from `/clarify-task`) or a direct task description.
+
+**Task description:** `$ARGUMENTS`
+
+## Step 0: Load context
+
+Load ALL knowledge skills by reading their SKILL.md files:
+- `scopy-architecture-knowledge` — core architecture patterns
+- `scopy-tools-inventory` — available development tools
+- `scopy-component-relationships` — how components interact
+- `scopy-decision-frameworks` — architectural decision trees
+- `external-research` — guidelines for researching external solutions
+
+Check if a task brief exists in `docs/design/` matching the topic:
+- Use Glob to search for `docs/design/*brief.md` files
+- If found, read it and use it as the primary input
+
+If `$ARGUMENTS` appears vague or underspecified (no concrete requirements, unclear scope):
+- Suggest running `/scopy_dev_plugin:clarify-task` first
+- But do NOT block — proceed if the user wants to continue
+
+## Step 1: Architecture analysis
+
+Using the decision frameworks skill, work through key architectural decisions:
+
+1. **Where does this belong?**
+   - Which package, plugin, or core library?
+   - Use the "Plugin vs Core Library" and "New Package vs Extend Existing" decision trees
+
+2. **What components need to be created vs modified?**
+   - Use Glob/Grep to find existing files that will be affected
+   - Read relevant source files to understand current structure
+
+3. **What patterns from the codebase apply?**
+   - ToolTemplate, IIOWidgetBuilder, MessageBroker, Preferences, etc.
+   - Use the "Tool vs Section", "IIOWidget vs Custom Widget", "Sync vs Async" decision trees
+
+4. **What external dependencies are needed?**
+   - If any, follow external-research skill guidelines
+   - Check license compatibility, cross-platform support
+
+**Present 2-3 architectural approaches** with trade-offs and your recommendation. Use AskUserQuestion to let the user choose. Format:
+
+```markdown
+### Approach A: <name> (Recommended)
+- **How it works:** <brief description>
+- **Pros:** <list>
+- **Cons:** <list>
+
+### Approach B: <name>
+- **How it works:** <brief description>
+- **Pros:** <list>
+- **Cons:** <list>
+```
+
+**Wait for user to choose before continuing.**
+
+## Step 2: Component design
+
+For the chosen approach, detail each component:
+
+### New Classes
+For each new class:
+- **Name** (following Scopy conventions: PascalCase, m_ prefix for members)
+- **Responsibility** (single responsibility)
+- **Inheritance** (PluginBase, ApiObject, QWidget, etc.)
+- **Key methods** (with signatures)
+- **File location** (following lowercase filename convention)
+
+### Modified Classes
+For each modified class:
+- **File path** and current structure
+- **What changes** and why
+- **Impact** on other consumers of this class
+
+### File Locations
+Map all new and modified files:
+```
+packages/<name>/plugins/<plugin>/
+├── include/<plugin>/
+│   ├── newclass.h          (NEW)
+│   └── existingclass.h     (MODIFIED)
+├── src/
+│   ├── newclass.cpp         (NEW)
+│   └── existingclass.cpp    (MODIFIED)
+├── CMakeLists.txt           (MODIFIED if explicit file lists)
+└── test/
+    └── tst_newfeature.cpp   (NEW)
+```
+
+### Data Flow
+Describe how components communicate:
+- Qt signals/slots connections
+- MessageBroker topics (if cross-plugin)
+- IIO data flow (attribute read/write, buffer streaming)
+- API exposure for test automation
+
+### Configuration
+- CMake changes needed (new targets, dependencies, flags)
+- manifest.json changes (if any)
+- Preferences entries (if any)
+
+## Step 3: Existing tools & patterns report
+
+Using the tools inventory skill, categorize what's available:
+
+### Reusable (use directly)
+- Existing utilities, widgets, or patterns that solve part of the problem
+- Reference specific files and explain how to use them
+
+### Adaptable (modify slightly)
+- Things that exist but need small changes
+- Explain what changes are needed and why
+
+### Missing (build from scratch)
+- What doesn't exist and must be created
+- Estimate relative complexity (simple/moderate/complex)
+
+### External (from outside Scopy)
+- Libraries or patterns found via research
+- Use the format from the external-research skill
+- Include "build it ourselves" as an alternative
+
+## Step 4: Testing & documentation strategy
+
+### Unit Tests
+- What to test with Qt Test framework
+- Mock strategy (if applicable)
+- File locations in `test/` subdirectory
+
+### JS Hardware-in-the-Loop Tests
+- What to test with JS HITL (patterns from `claude_scopy_dev_plugin` branch)
+- API methods needed for automation
+- Hardware requirements
+
+### Manual Test Cases
+- RST test documentation with UIDs and RBP priority levels
+- Category A (automatable), B (visual), C (manual only) breakdown
+
+### API Class
+- Is a Q_INVOKABLE API class needed?
+- What methods to expose
+- Conversion rules for IIO attributes
+
+### Documentation
+- User guide sections (RST format)
+- What's New entry for releases
+
+## Step 5: Present design
+
+Present the full design in conversation, organized as:
+
+1. **Architecture Overview** — chosen approach, component diagram
+2. **Component Details** — new/modified classes, file locations
+3. **Data Flow** — how components communicate
+4. **Existing Tools Report** — reusable/adaptable/missing/external
+5. **Testing Strategy** — unit, HITL, manual, API
+6. **Implementation Order** — suggested sequence of implementation steps
+
+Ask after each major section: "Does this look right so far?" using AskUserQuestion.
+
+## Step 6: Save design document
+
+Ask the user:
+> "Would you like me to save this design document to `docs/design/YYYY-MM-DD-<topic>-design.md`?"
+
+If yes, write the complete design document to file.
+
+## Step 7: Transition
+
+After the design is complete and saved, suggest next steps:
+
+> **Next steps:**
+> - Run the `writing-plans` skill to create a detailed implementation plan from this design
+> - Or use specific commands for individual pieces:
+>   - `/scopy_dev_plugin:create-api <plugin>` for the API class
+>   - `/scopy_dev_plugin:create-docs <plugin>` for documentation
+>   - `/scopy_dev_plugin:create-automated-tests <plugin>` for test automation
+
+## Rules
+
+- Do NOT write any code or modify source files — this command produces only a design document
+- Always present 2-3 approaches before detailing one — let the user choose
+- Always check for existing patterns before proposing new ones
+- Always evaluate external solutions using the external-research skill criteria
+- Reference specific files and line numbers when discussing existing code
+- Follow Scopy naming conventions in all proposed class/file names
+- Include testing strategy — every feature needs a test plan
+- The design document should be detailed enough that someone could implement from it