Feature Refinement Flow
Productivityfeature-refinement-flowFeature Refinement Flow is an Agent Skill for productivity published in the rcarmo/piclaw repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Run a structured 20-question refinement flow before implementation for feature requests.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/rcarmo/piclaw/blob/HEAD/skel/.pi/skills/feature-refinement-flow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/feature-refinement-flow, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Feature Refinement Flow
Use this skill to turn a feature request into a clear, implementation-ready work item.
When to use
Invoke when a request includes:
- behavior changes,
- new integrations,
- UI/editor workflow changes,
- or non-trivial architectural decisions.
Goal
Turn vague ideas into:
- A concrete user outcome
- A deterministic implementation scope
- A reproducible test plan
Default process
Ask up to 20 questions in sequence, one-at-a-time, unless already answered.
20-question baseline
- What is the problem statement and why does it matter now?
- Who is the primary user and what workflow do they follow today?
- What are the success criteria (observable outcomes)?
- What is the MVP behavior (minimum useful version)?
- What is explicitly out of scope?
- Which files/surfaces are in scope (frontend, backend, extension API, tests)?
- Any required platform constraints (browser support, runtime limits, auth mode)?
- What should happen on error/failure cases?
- What is required for data persistence / storage semantics?
- Which existing pattern should this align with?
- What should be changed first (lowest-risk slice)?
- What should we avoid for v1?
- How should file types, formats, and naming be handled?
- Who/what are the inputs and outputs of this feature?
- What should happen to existing behavior during this change?
- What are the expected performance and startup/load constraints?
- What security / permissions concerns apply?
- What should be exportable / shareable and in which format(s)?
- How will we prove this works (test plan)?
- What is the acceptance/closure condition for “done”?
How to use in work items
- Add a short “Refinement notes” section in the work item with the 20-question answers.
- Convert answers into:
- acceptance criteria,
- risks,
- implementation path,
- test plan,
- definition of done.
- Add blockers only where known (uncertain candidate APIs, policy issues, missing assets).
Preference persistence
Keep answers in a feature-scoped notes/work-item file or notes/preferences/feature-refinement.md if the process becomes reusable.
Web UI / Adaptive Card note
When the user is in the PiClaw web UI, you may use a compact Adaptive Card for refinement questions when it is materially better than markdown — especially for:
- single-choice follow-up questions
- short structured confirmations
- approval / pick-one-next-step decisions
Rules:
- still ask one question at a time unless the user has already answered later items
- prefer markdown if it is clearer or less heavy-weight
- use the current
adaptive-cards-authoringskill/runtime constraints - keep cards compact, with concise fallback text and supported actions only
- do not turn the whole 20-question flow into a giant form; cards are for selective structured steps, not bulk interrogation
Practical tip
Prefer narrow first, iterate later: lock scope by answering 1–10 first, then expand with dependency/testing details only after behavior is clear.