Skip to main content

Requirements Clarification

Source: .agents/references/implementation/requirements-clarification.md

Content​

Requirements Clarification

Use this before creating the master checklist for .agents/skills/implement-feature/SKILL.md.

Required Inputs​

The master agent must collect, derive from context, or explicitly mark not applicable:

  • Product requirement
  • Design spec, Figma URL, screenshot, or "no design dependency"
  • Acceptance criteria
  • Lark channel link or "not provided / skipped"
  • Target users and user flows
  • Edge cases and failure modes
  • API/backend dependencies and API integration mode
  • Analytics or tracking requirements
  • Localization requirements
  • Permission, plan, role, or feature-flag requirements
  • Testing expectations
  • Rollout, backward compatibility, and migration concerns

Dependency Discovery​

Before asking questions, inspect discoverable context:

rtk rg "<feature keyword>" .agents src
rtk find .agents/references/features -maxdepth 1 -type f
rtk find src -maxdepth 3 -type d

Load:

  • AGENTS.md
  • .agents/rules/*.mdc
  • .agents/skills/feature-context/SKILL.md
  • Relevant .agents/references/features/*.md
  • Relevant .agents/references/coding-standard/*.md

Then inspect likely route, component, hook, service, utility, and test files.

Blocking Questions​

Ask only for decisions that cannot be discovered from repo context and would change the implementation. Examples:

  • Which user role or plan should receive the behavior?
  • Which Figma node/design state is canonical?
  • Is there a Lark channel link with product, API, QA, or rollout context? If not provided, should it be skipped for this feature?
  • Is analytics required, and what event contract should be used?
  • Should a temporary plan file be preserved after completion?
  • Is a backend/API change already available or should frontend mock/fallback behavior be planned?

API Documentation Handling​

Classify API/backend dependencies before checklist creation:

  • provided: API docs, contracts, or existing service contracts are available and should be used.
  • ui-only: API docs are missing, but UI implementation can proceed without real API integration.
  • blocked: API docs are missing and real backend behavior is required for implementation.
  • not-applicable: The feature has no API/backend dependency.

If API docs are missing, the master agent must explicitly offer the user the option to proceed with UI-only implementation without API integration. UI-only work must not invent API contracts, service methods, response shapes, backend behavior, or backend error handling. Record what is intentionally excluded from UI-only tasks, including real service integration, request/response typing, backend error handling, and end-to-end API tests.

If the feature requires real backend behavior and no API docs or existing contracts are available, mark the API integration mode as blocked and do not assign implementation tasks that depend on the missing contract.

Do not ask where code lives when search can answer it.

Clarification Output​

Before checklist creation, produce a short clarification summary:

## Clarified Requirements

- Product requirement:
- Design source:
- Acceptance criteria:
- Lark channel link: provided | skipped | not-applicable
- Target users/flows:
- Edge cases:
- API/backend dependencies:
- API integration mode: provided | ui-only | blocked | not-applicable
- UI-only exclusions:
- Analytics:
- Localization:
- Permissions/flags:
- Tests:
- Rollout/backward compatibility:
- Open blockers:

If Open blockers is not empty, do not assign implementation tasks.