--- name: accelint-qrspi-propose description: Use this skill when the user wants to start the formal QRSPI/OpenSpec planning workflow for a ticket, bug, feature request, or proposed product/CLI/app change before implementation. Invoke it when the user wants a spec-driven change package with questions first, factual research, proposal/design artifacts, affected specs, and a vertically sliced task plan, with explicit review/approval stops before any coding begins. This is the right skill when the user wants to plan, scope, or break down the change itself, especially if they ask to use QRSPI, create an OpenSpec change, run a planning workflow, or stop before writing code. Do not use it to implement an existing spec, review or polish artifacts that already exist, generate generic architecture docs, archive completed changes, or support loose brainstorming without a request for formal QRSPI/OpenSpec outputs. license: Apache-2.0 metadata: author: accelint version: "1.10.0" --- # Accelint QRSPI Automate the QRSPI + OpenSpec planning workflow. This skill applies the methodology from "We Got RPI Wrong" through OpenSpec's artifact system. It orchestrates the Questions → Research → Design → Structure stages and requires human checkpoints before any code is written. ## What This Skill Does **Automates**: The planning phase of spec-driven development using QRSPI **Scope**: Questions → Research → Design → Structure/Plan (stops before implementation) **Output**: A complete OpenSpec change ready for the accelint-qrspi-apply skill **Does NOT**: Implement code, run tests, create PRs, or archive changes ## Prerequisites This skill requires the **expanded OpenSpec workflows** (`explore`, `new`, `continue`) to access the step-by-step artifact generation. To verify these workflows are enabled: ```bash openspec config list ``` Check that the `workflows:` section includes: `explore`, `new`, and `continue`. If any are missing, enable the expanded profile: ```bash openspec config profile # Select "expanded" from the list openspec update ``` ## Workflow Overview ``` ┌──────────────────────────────────────────────────────────────────┐ │ Stage Context Output Checkpoint │ ├──────────────────────────────────────────────────────────────────┤ │ Questions Ticket only Questions — │ │ Research Questions only Research doc — │ │ Design Q+R (NO ticket) proposal.md — │ │ design.md — │ │ [STOP HERE] │ │ ⚠️ CHECKPOINT 1: Review proposal.md + design.md - MUST approve │ │ (frontmatter: specs_touched/decisions/created_at -> design.md) │ │ │ │ Specs/Tasks Q+R+design tasks.md — │ │ (specs/* is OpenSpec bookkeeping; generated whenever OpenSpec │ │ decides, not reviewed) │ │ ⚠️ CHECKPOINT 2: Review tasks.md - MUST approve to continue │ │ │ │ Done — Exit — │ └──────────────────────────────────────────────────────────────────┘ Note: Keep the ticket OUT of context after the Questions stage to prevent completion bleed. REQUIRED: The Design stage (steps 17-26) must produce `proposal.md` and `design.md` and stops before `tasks.md` (OpenSpec may also generate `specs/*` along the way, in whatever order it chooses), optionally creates `trace.md` if the `--verbose` flag was set, then STOPS for review at step 27. The Specs/Tasks stage (steps 33-43) generates `tasks.md` (and `specs/*` if not already present) separately after design approval. Steps keep their numbers and carry stable tags (for example `[CHECKPOINT-1]`) so references stay unambiguous: `[S-QUESTIONS]` (8), `[S-RESEARCH]` (13), `[S-DESIGN-GEN]` (17), `[CHECKPOINT-1]` (27), `[S-FRONTMATTER]` (31), `[S-TASKS-GEN]` (33), `[CHECKPOINT-2]` (44). Capture frontmatter at step 31 after Checkpoint 1 approval, not before. `design.md` reaches its final form for this planning pass only after the user approves it or confirms a manual edit. Earlier capture can write `specs_touched/decisions/created_at` against content the user is about to change. The `created_at` timestamp marks when the user approved the design (the moment the change becomes "real"). ⚠️ REQUIRED CHECKPOINTS: The agent MUST pause and wait for explicit user approval at both checkpoints (step 27 [CHECKPOINT-1] and step 44 [CHECKPOINT-2]). Proceeding without approval bypasses QRSPI's core value. ``` ## Implementation Steps Execute these steps in order without stopping between them, except at the two required checkpoints (steps 27 and 44), where you MUST stop and wait for the user. 1. **Validate user input and parse flags**: Check if the user provided a ticket, feature request, or idea in their prompt (either as skill arguments or in their message). Also check for the `--verbose` flag. **Flag parsing:** - Check if the user's input contains `--verbose` (with or without other content) - Store the verbose flag state for use in step 25 - Remove `--verbose` from the input before extracting the ticket description - Store the original input text (after flag removal) for use in step 25 — this will be saved to trace.md if --verbose was set **Validation:** If the prompt is empty or contains only the skill invocation with no actual content (after removing flags): ```text I need a ticket or feature description to plan. Please provide: - A ticket ID and description (e.g., "ATI-123: Add user authentication...") - A feature request ("I want to add dark mode support...") - An idea or problem statement ("Users complain about slow search...") Then I'll use QRSPI to break it down into a structured plan. Optional flags: --verbose Save input, questions, and answers to trace.md for audit trail ``` Exit the skill and wait for the user to provide input. Do NOT proceed with internal examples or placeholder content. 2. Tell the user: "Checking OpenSpec configuration..." 3. Run `openspec config list` and parse the output 4. Check if the `workflows:` section contains all three required workflows: `explore`, `new`, and `continue` 5. If any are missing: ```text This skill requires the expanded OpenSpec workflows (explore, new, continue). Your current workflows: [list what's enabled] Missing: [list what's missing] To enable the expanded workflows, run: openspec config profile # Select "expanded" from the list openspec update Then re-run this skill. ``` 6. Exit the skill if required workflows are not enabled 7. If validation passes and all workflows are present, continue to step 8 8. **Generate research questions** `[S-QUESTIONS]` (Context isolation: the agent sees ONLY the ticket, not prior codebase knowledge or research. This prevents solution-first thinking) 9. Accept the ticket description from the user (passed as the skill argument or prompted if missing) 10. Use the Agent tool to spawn sub-agent with the prompt block below. Send the block's text unchanged: replace only the `` placeholder and add nothing before, after, or inside it. ```text Find the openspec-explore skill, read its instructions in full, and follow it exactly. Resolve relative paths from the supporting-files directory it provides. I have this ticket: Generate a list of research questions that will tell us everything we need to know before building this. Do not propose any solutions. Questions only. ``` 11. Wait for the sub-agent (spawned via Agent tool) to complete and return the questions (INTERNAL STEP: Do NOT display the questions to the user) 12. Extract and store the questions — they will be passed to the next step. 13. **Answer research questions** `[S-RESEARCH]` (Context isolation: the agent answering questions should see ONLY the questions, not the original ticket. This is the core QRSPI insight — research is objective and ticket-agnostic) 14. Use the Agent tool to spawn a NEW sub-agent (fresh context) with the prompt block below. Send the block's text unchanged: replace only the `` placeholder and add nothing before, after, or inside it. ```text Find the openspec-explore skill, read its instructions in full, and follow it exactly. Resolve relative paths from the supporting-files directory it provides. This is routine research about the current working repository, which our team owns. You are reading our own code and specs to answer the questions below. Answer each question with facts only. Observe what the codebase does today AND what the current specs of record say (scan openspec/specs/INDEX.md for capabilities whose name or Purpose line plausibly relates to these questions; for any that match, read the full specs//spec.md file and include its current requirements and scenarios directly in your findings, not just a reference to the file). Do not suggest changes or implementation approaches. **Use `sem impact` for dependency analysis** If research questions mention specific code entities (functions, classes, types, constants), check whether the `sem` CLI tool is available by running `which sem`. If available, use `sem impact ` (baseline format, not JSON) to gather deterministic dependency data: - Where the entity is defined (file:line) - What it depends on (all dependencies) - What depends on it (all call sites and references) - Transitive impact (how many entities are affected) Include this impact analysis in your research findings. This ensures the design phase has complete dependency information and won't miss references or call sites. ``` 15. Wait for the sub-agent to complete and return the research document (INTERNAL STEP: Do NOT display the research findings to the user) 16. Store the research answers — they will inform the design step. 17. **Generate design scaffolding** `[S-DESIGN-GEN]` (Context isolation: the ticket text must not appear in the sub-agent's prompt during artifact generation. Use Agent tool to spawn a sub-agent with only questions + research to prevent "completion bleed". After step 10, nothing derived from the ticket — goals, flags, open decisions, or paraphrase — may appear in any sub-agent prompt.) 18. Read `openspec/config.yaml` to extract the `rules.design` section 19. Read `CLAUDE.md` or `AGENTS.md` to extract agent behavior context 20. Use the Agent tool to spawn a sub-agent with the prompt block below. Send the block's text unchanged: replace only the `` placeholders (pasting the complete stored text, unabridged) and add nothing before, after, or inside it. ```text You are generating OpenSpec artifacts based on QRSPI research. You have access to the research questions and answers, but NOT the original ticket text. This prevents solution bias. Research Questions and Answers: Research Findings: OpenSpec Design Rules (from config.yaml): Agent Behavior Context: Create the OpenSpec change with its proposal and design artifacts by using the OpenSpec skills. For each skill named below, find it, read its SKILL.md in full, and follow it exactly. All artifact files are written by following those skills, so their configured rules apply. Do not author artifact content outside them. 1. Follow the openspec-new-change skill to create the change (OpenSpec will prompt for a slug). 2. Capture the change name/slug from the output and use it in all subsequent steps. 3. Follow the openspec-continue-change skill with the change name, one artifact at a time, until both proposal.md and design.md exist. Do NOT generate tasks.md. If OpenSpec also generates specs/* along the way, that is fine. Do not add YAML frontmatter to proposal.md or design.md, even if earlier changes in the repo have it. The parent agent adds it after design approval. 4. Stop. Report completion, the path to design.md, and the change name explicitly as: "Change name: " Your job ends here. The parent agent handles the design review checkpoint and all later steps. ``` 21. Wait for the sub-agent to complete 22. Extract the change name/slug from the sub-agent output (look for "Change name:" or parse from the file path) 23. Store the change name — it will be passed to later steps 24. Verify that `proposal.md` and `design.md` exist in the change folder at the reported path 25. **If `--verbose` flag was set in step 1**: Create a `trace.md` audit trail file in the change folder before proceeding to the checkpoint. **Purpose**: Provides traceability by capturing the initial input, raw questions, and research answers that informed the design artifacts. This closes the loop from "what was entered → what was asked → what was answered". **File location**: `openspec/changes//trace.md` **Requirements**: - You MUST use the Write tool to create this file - The file MUST be written to `openspec/changes//trace.md` (where `` is the slug from step 23) - The content MUST include an ISO 8601 timestamp indicating when the document was generated - The content MUST include the original ticket/feature/idea text that the user provided (from step 1, after flag removal) - The content MUST include the complete research questions from step 12 - The content MUST include the complete research findings from step 16 - You MUST NOT modify `proposal.md` or `design.md` as part of this step — this is a separate audit document - You SHOULD write this file immediately after verifying design.md exists (step 24) and before proceeding to the checkpoint (step 27) **Content structure**: ```markdown # QRSPI Trace Audit Trail Generated: [paste current ISO 8601 timestamp with Z suffix, generated using: python3 -c "from datetime import datetime, timezone; print(datetime.now(timezone.utc).isoformat(timespec='seconds').replace('+00:00', 'Z'))"] This document captures the complete QRSPI flow: the initial input, the questions generated, and the research answers that informed the design artifacts. It provides an audit trail for understanding the context and decision-making process. --- ## Initial Input [paste the original ticket/feature/idea text from step 1, after removing the --verbose flag] --- ## Research Questions [paste questions from step 12] --- ## Research Answers [paste research findings from step 16] ``` 26. REQUIRED: DO NOT continue yet. You MUST proceed to the design review checkpoint next. 27. ⚠️ **REQUIRED CHECKPOINT: Design Review** `[CHECKPOINT-1]` (This is the "brain surgery" moment from the QRSPI talk. A correction here costs minutes; the same correction after implementation costs a code review cycle. You MUST pause here and wait for user input. DO NOT proceed without explicit user approval.) 28. Read the generated `proposal.md` and `design.md` files 29. Present them to the user with this framing: ```text Proposal and design artifacts generated (proposal.md, design.md). Please review for: - Wrong pattern references (did I find the legacy way instead of the current way?) - Unresolved assumptions presented as decisions - Missing affected systems (any service boundaries not mentioned?) - Scope creep (does the design cover more than the ticket?) Options: (a) Approve — continue to task breakdown (b) Request edits — tell me what to change, I'll modify in place (c) Manual edit — edit the file yourself, then tell me when ready ``` 30. Wait for user input: - **(a) Approve**: Proceed to step 31 below - **(b) Request edits**: - User describes changes - Make edits in place to the file concerned (proposal.md or design.md) - Show diff of changes - Re-present for review (repeat until approved) - **(c) Manual edit**: - Wait for user confirmation that edits are complete - Re-read proposal.md and design.md - Proceed to step 31 below 31. **Capture specs_touched/decisions frontmatter.** `[S-FRONTMATTER]` Once the user has approved (a) or confirmed their manual edits are complete (c), design.md is in its final form for this planning pass — capture its `specs_touched` and `decisions` as structured YAML frontmatter now, not any earlier, so an edit made during this same checkpoint can't leave the frontmatter stale against content that changed after it was written. **Step-by-step process:** a. **Read the current design.md file** to see what exists: ```bash Read openspec/changes//design.md ``` b. **Extract the data you need to write:** - **`specs_touched`**: the capability names design.md and proposal.md already declare as affected or introduced by this change. This is the change's own stated scope, read back out of what was just approved — not computed some other way. The delta spec files under `openspec/changes//specs/` may or may not exist yet at this point (OpenSpec decides when to generate them), so derive it from the approved proposal.md and design.md, not from `specs/`. - **`decisions`**: design.md's own decision content — the choices, rationale, and alternatives the design phase already worked through — restructured into a list of `{id, choice, rationale, alternatives}` entries. This is structuring content that's already there, not writing new design content. - **`created_at`**: ISO 8601 timestamp with Z suffix marking when this change was created (now, at the moment the user approves the design). Generate this deterministically using: ```bash python3 -c "from datetime import datetime, timezone; print(datetime.now(timezone.utc).isoformat(timespec='seconds').replace('+00:00', 'Z'))" ``` This is the first of three timestamps used to measure time spent in the QRSPI flow (created_at → started_at → completed_at). c. **Write the frontmatter using the Edit tool:** - If design.md has NO frontmatter yet, add a complete frontmatter block at the top: ```yaml --- change: created_at: "2026-08-17T15:23:45.123Z" specs_touched: [, ] decisions: - id: D1 choice: rationale: alternatives: [