OpenParable
Skip to content
← Back to skills

Feature Refinement Flow

Productivity
feature-refinement-flow

Feature 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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:

  1. A concrete user outcome
  2. A deterministic implementation scope
  3. A reproducible test plan

Default process

Ask up to 20 questions in sequence, one-at-a-time, unless already answered.

20-question baseline

  1. What is the problem statement and why does it matter now?
  2. Who is the primary user and what workflow do they follow today?
  3. What are the success criteria (observable outcomes)?
  4. What is the MVP behavior (minimum useful version)?
  5. What is explicitly out of scope?
  6. Which files/surfaces are in scope (frontend, backend, extension API, tests)?
  7. Any required platform constraints (browser support, runtime limits, auth mode)?
  8. What should happen on error/failure cases?
  9. What is required for data persistence / storage semantics?
  10. Which existing pattern should this align with?
  11. What should be changed first (lowest-risk slice)?
  12. What should we avoid for v1?
  13. How should file types, formats, and naming be handled?
  14. Who/what are the inputs and outputs of this feature?
  15. What should happen to existing behavior during this change?
  16. What are the expected performance and startup/load constraints?
  17. What security / permissions concerns apply?
  18. What should be exportable / shareable and in which format(s)?
  19. How will we prove this works (test plan)?
  20. 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-authoring skill/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.