Lab 3 · Create reusable prompts

Context

So far, you used the chat interface to generate code directly.

Now you will create a reusable workflow step that specifically supports clarifying and agreeing requirements for the features you want to implement.

Your Task

Start the lab setup with the following command:

task lab/research

IMPORTANT

If you work in GitHub Codespaces, open a new Codespace on branch lab/research.

After the command is finished, complete the following tasks:

• Describe the task in .agents/skills/research/SKILL.md: critically review requirements, surface gaps, refine requirements, and write an improved specification.
• Make the skill invocable only by the user, not by other agents, via its frontmatter.
• Invoke the skill to create the specification for:
  • GET /delays?airline_code=AA&limit=50
• Check the specification it writes to specs/<slug>/specification.md.

NOTE

The TODO markers in the relevant files will help you get started.

Solution

.agents/skills/research/SKILL.md

---
name: research
description: Critically review a requirement, surface gaps, refine requirements, and write an improved spec.
disable-model-invocation: true
---

## TASK

You are exploring and refining a requirement and writing an improved specification. Be concise, critical, and pragmatic.

The resulting specification must describe how the change should behave from an API/user perspective, and must not contain unnecessary implementation details.

The improved specification must be readable by both a human (for further refinement) and a coding agent (for implementation).

You MUST NOT make any code changes or offer to make any code changes as part of this task. This task is purely to refine the requirement.

---

## STEPS

1. Analyze the requirement based on the user’s prompt to make sure you understand it.
   - If necessary, read targeted parts of the codebase to understand current behavior from a user perspective.

2. Detect and list gaps or ambiguities (missing acceptance criteria, unclear ownership, implicit assumptions, vague terms, hidden dependencies, sequencing conflicts).

3. Ask the user at most the 5 highest-impact clarifying questions (only those that block correct implementation or carry high risk). Skip trivial questions.
   - If something is uncertain but non-critical, make and state a sensible assumption instead of asking.

4. Draft improved, implementation-ready requirements:
   - Title: the outcome, from the user's perspective
   - Context (1–2 sentences)
   - Acceptance Criteria (objectively testable, false at the current commit)
   - Constraints, Non-goals, Assumptions and Risks (if any)

5. Apply the **handoff-writing skill** to write the research-phase handoff, `specs/<slug>/specification.md`.

6. Output a short summary to the chat (not the file):
   - assumptions made
   - clarifications received

7. Ask the user for feedback and incorporate it into the handoff document in a follow-up pass.

---

## ASPECTS TO CONSIDER FOR API DESIGN

- What should the endpoint URLs be?
- What parameters should they accept?
- What response format should they return?
- What HTTP status codes should be used for different scenarios?
- How should this feature align with existing endpoints?
- What naming conventions should be followed?
- What response format patterns should be maintained?
- Are there any mathematical edge cases (e.g., division by zero, overflow)?

---

## PRIORITIZATION RULES

- Favor clarity over completeness; remove noise.
- Reject scope creep: if not traceable to the stated objective, ask the user for clarification.
- Ensure each acceptance criterion is objectively testable.
- Avoid solution bias unless mandated by constraints.

---

## ADDITIONAL RULES

If the user’s prompt is fundamentally insufficient, refuse to review it and ask the user to provide at least a minimal set of requirements.