Generate Test Plan

Generate Test Plan from Source (FRS / Raw Code)

This skill produces QA-focused E2E test plans from a Functional Requirements Specification (FRS) or raw application source code. It does three things in parallel that QA reviews have shown are all needed for good coverage:

1. Walks the FRS structurally — every section that can produce TCs (FRs, ACs, Exception Flows, Edge Cases, Business Rules, Alternative Flows, Notifications, Form Fields) is processed in turn so no section is silently skipped.
2. Walks a Required Coverage Matrix — implicit TCs (duplicate values, max length, required fields, format, modal dismissal patterns, read-only enforcement, state transitions, cross-field rules, session edge cases, multi-tenancy, authorization, concurrency) are emitted whenever the data model or operation type implies them, regardless of whether the source enumerates them.
3. Traces every TC back to its source — FR-ID, AC-ID, BR-ID, EC-ID, exception flow ID, or "Matrix" — so QA can audit coverage section by section.
4. Generates Test Data per TC — populates a ## Test Data section in every TC, with concrete or templated values derived from each field's constraints and the TC's matrix intent. Consumed by generate-test-suite (phase 2) at codegen time. See references/test-data-generation.md for the value-generation rules.

Workspace Layout Assumption

This skill assumes a multi-repo workspace where the docs/wiki repo lives alongside the UI and API repos — typically as a sibling, sometimes one level higher:

workspace/
  ui/        ← frontend repo (skill may be run from here)
  api/       ← backend repo (skill may be run from here)
  docs/      ← wiki / knowledge repo (TC files land here)

Or a nested layout where the docs repo sits at the workspace root:

workspace/
  frontend/
    ui/      ← skill may be run from here
  backend/
    api/     ← skill may be run from here
  wiki/      ← docs repo lives here

Common names for the docs/wiki repo: docs, wiki, knowledge, kb, documentation. The skill discovers the path automatically (Step 1) and asks the user when discovery is ambiguous or fails.

Throughout this skill, the resolved path is referred to as {docs_repo}. All TC paths take the form {docs_repo}/test-plans/{feature}/{use-case}/{feature}-TC-{NNN}.md.

Directory Structure

{docs_repo}/test-plans/
  {feature}/
    {use-case-a}/
      {feature}-TC-001.md     ← happy path
      {feature}-TC-002.md     ← validation / edge case
    {use-case-b}/
      {feature}-TC-003.md     ← happy path
      {feature}-TC-004.md     ← error handling
    ...

Naming rules:

• Feature folder: kebab-case (checklist, service-type, verification-preview)
• Use case sub-folder: kebab-case verb or action (display, add, edit, delete, toggle, reorder, search, export, view, preview, auth)
• TC file: {feature}-TC-{NNN}.md — sequential across the entire feature, not per sub-folder

TC File Format

# {feature}-TC-{NNN}: {Title} ({Category})

**Feature:** {Feature Name}
**Scenario:** {Letter} — {Scenario description}
**Priority:** {High | Medium | Low}
**Type:** Functional
**Tags:** @smoke @{feature} @{feature}-TC-{NNN}
**Traces to:** {FR-ID(s) | AC-ID(s) | BR-ID(s) | EC-ID(s) | Exception-Flow-ID(s) | Matrix: <row name>}

---

## Steps

| # | Step | Selector | Expected Result |
|---|------|----------|-----------------|
| 1 | Navigate to {path} | `n/a` | Page loads, {visible landmark} |
| 2 | Click "{button}" button | `[data-testid="{testid}"]` | {what happens} |
| 3 | Enter "{value}" in {field} | `[data-testid="{testid}"]` | {what appears} |
| 4 | Verify {element} | `(discovered by explorer)` | {expected state} |

---

## Preconditions
- {precondition 1}
- {precondition 2}

## Postconditions
- {postcondition 1}
- {postcondition 2}

## Test Data

### Pre-existing State
- {prose description of database state required before the test runs — e.g. "A Rule Template with Code 'TC-DUP-001' exists"}
- {prose description of user/role/permission state}

### Form Input
* {Field Name 1}: {value or templated value or `description → directive(args)`}
* {Field Name 2}: {value}
* {Field Name 3}: {value}

### Pre-existing State is omitted entirely when the TC needs no database state (most happy-path TCs). ### Form Input is omitted when the TC has no fill / select / toggle steps (pure read/view TCs).

Format rules

• Title includes the category in parentheses: (Happy Path), (Validation), (Duplicate), (Max Length), (Authorization), (Read-Only), (Dismissal), (Edge Case), (Error Handling), (State Transition), (Cross-Field), (Concurrency), (Multi-Tenant), (Guard), (PENDING — OQ-NN)
• Scenario line uses a letter prefix: A — Preview face row (Happy Path), B — Preview row with capture missing (Edge Case)
• **Traces to:** line is mandatory — list every source ID this TC verifies, plus matrix row name if matrix-driven
• @smoke tag only on happy-path TCs
• Steps table columns: #, Step, Selector, Expected Result — in that order
• Selectors are backtick-wrapped: `[data-testid="..."]`, `n/a`, or (discovered by explorer) (no backticks for placeholder)
• Dynamic selectors use the template notation with curly braces: `[data-testid="checklist-row-{item.id}"]`
• Preconditions describe the required state before the test runs (data, role, environment, session state)
• Postconditions describe the expected system state after all steps pass (UI state, DB state if applicable, audit log entry, modal closed/open)
• Test Data has up to two sub-sections: ### Pre-existing State (prose, for DB/auth/permission state) and ### Form Input (one bullet per field touched by fill/select/toggle steps). Field names match the FRS Form Fields section verbatim (human-readable, not camelCase). Values are concrete literals, templated tokens ({timestamp}, {counter}, {uuid}, {tcNumber}), or description → directive(args) for matrix-driven violations. See references/test-data-generation.md for the value-generation rules and directive vocabulary.
• Horizontal rules (---) separate the header, steps, and conditions sections
• For PENDING TCs, the title is prefixed PENDING — OQ-NN — and Postconditions name the OQ-ID being awaited

FRS Section Walkthrough

When the input is an FRS, walk every section that produces TCs in the order below. Each section has its own extraction recipe. The frs-generator skill emits FRSes with sections numbered 1–23; this walkthrough refers to sections by name so it applies to any well-structured FRS, with the typical section number in parentheses for reference.

The walkthrough is the first TC source. Source-driven TCs from raw code (Step 4) and matrix-driven TCs (Step 6 Pass 2) are layered on top. Dedup across sources is done in Step 6.

Trigger (§9) + Main Flow (§10)

• Emit one Happy Path TC that exercises the trigger and walks every step of the main flow.
• Tag with @smoke. Priority: High.
• Trace to: every FR-ID invoked along the flow + AC-IDs that map to flow steps.
• The Postconditions section quotes Section 13 (Postconditions, "On success") of the FRS verbatim where applicable.

Alternative Flows (§11)

• One TC per alternative flow (11a, 11b, …).
• Title pattern: {Feature} — {Alt flow name} (Alternative Flow).
• Trace to: the alt flow's branch step + FR-IDs the alt flow exercises.
• If an alt flow only changes input data (e.g. "Face Verification Row Preview" vs. main flow being agnostic), the alt flow TC may consolidate into the main flow TC for the variant; in that case, add a separate TC for the other variant explicitly.

Exception Flows (§12)

• One TC per exception flow (12a, 12b, 12c, …).
• The exception's Trigger → reproduce as a Step in the TC.
• The exception's Outcome → assert as the Expected Result of the triggering step.
• The exception's Resolution → noted in Postconditions as the recovery path.
• Title pattern: {Feature} — {Exception name} (Error Handling) or (Edge Case) for non-error exceptions.
• Trace to: the exception flow ID (e.g. EX-12a) + any FR-IDs that mandate the exception behaviour.

Functional Requirements (§16)

• Every FR-ID must trace to at least one TC by the end of Step 6. This is verified in Step 10's coverage report.
• FRs that are pure flow restatements (e.g. "system SHALL present a modal when icon is selected") are typically already covered by the Main Flow TC — note the trace, do not emit a duplicate.
• FRs that assert negative properties — "SHALL be read-only", "SHALL NOT allow X", "SHALL contain no input fields" — get their own dedicated Read-Only / Guard TCs because they require explicit absence verification, not flow execution.
• FRs that assert quantitative properties — "exactly two images", "at most 50 results" — get their own assertion TC.
• FRs that assert labelling / identification properties — "clearly labelled", "unambiguously identified" — get their own UI-content TC.

Acceptance Criteria (§17)

• One TC per AC-ID unless the AC is a pure restatement of a flow already covered by an exception or alt-flow TC; in that case, attach the AC-ID to the existing TC's Traces to line and do not duplicate.
• AC table in the FRS already shows traceability (Traces to: FR-VP-01-01, FR-VP-01-02). Carry that traceability into the TC.
• ACs framed as observable conditions (After X, the user sees Y) translate directly: precondition = X, expected result = Y.

Business Rules (§20)

• One TC per verifiable BR.
• BRs that are tautologies or pure scope statements (e.g. "this is read-only") may be skipped if a Read-Only Guard TC already covers them — in that case, attach the BR-ID to the existing TC's Traces to.
• BRs that constrain availability ("preview is available only for the Agent's currently active session") map to authorization / scope TCs.
• BRs that constrain presentation ("two images shall be presented in a consistent, labelled arrangement for every row type") map to UI-consistency TCs that exercise multiple inputs and assert the consistent rendering.

Edge Cases (§21)

• One TC per EC-ID.
• An EC may overlap with an exception flow (e.g. EC-01 "captured image not yet taken" overlaps with 12a "image retrieval failure"). When an EC is genuinely a sub-case of an exception, attach the EC-ID to the exception TC's Traces to and emit a more specific TC only if the EC adds a distinct precondition or assertion.
• ECs referencing an Open Question → emit as a PENDING — OQ-NN TC.

Notifications (§14)

• If the section is None, skip — do not invent notification TCs.
• Otherwise, emit one TC per notification covering: trigger event, recipient, channel, content. If the notification is sent to an external system (email, SMS, webhook), include verification of delivery in Postconditions.

Form Fields (§15)

• If the section is None, skip the per-field validation walk — the operation has no actor-facing data entry.
• Otherwise, for each field in the table, walk the Required Coverage Matrix rows for Create/Edit (required, max length, format, duplicate, whitespace, special chars, range) using the field's declared constraints.

Postconditions (§13) and Preconditions (§6)

• These feed the Preconditions and Postconditions sections of every TC, not standalone TCs.
• The FRS Preconditions list constrains the test setup; the FRS "On success" Postcondition is the assertion target for happy-path TCs; "On failure" Postconditions inform exception-flow TCs.

Open Questions (§22)

• Do not invent answers.
• Any TC whose content depends on an OQ → prefix title with PENDING — OQ-NN — and note the OQ in Postconditions.
• TCs that mention an OQ should still be emitted as placeholders so they aren't forgotten when the OQ resolves.

Scope — Out of Scope (§3)

• Items in the "Out of scope" list are NOT test targets.
• If an out-of-scope item could plausibly appear in the UI as a defect (e.g. an "annotation tool" in a read-only modal), emit at most one Guard TC asserting its absence. Label it (Guard).

Auditability (§19)

• If the FRS specifies operation-specific audit obligations beyond cross-cutting defaults, emit one TC per audit assertion (verify the audit log entry contains the expected fields after the action).
• If the section defers entirely to cross-cutting defaults and the operation is read-only, no TCs are required from this section.

Sections that do NOT produce TCs

• Purpose (§1), Assumptions (§2), Glossary (§4), Actors (§5), Dependencies (§7), Data Entities (§8), NFRs (§18), Revision History (§23) — these provide context for extraction but do not directly emit TCs. Data Entities (§8) feeds the data-model fact sheet used in matrix Pass 2.

Required Coverage Matrix

This is the floor for every test plan, regardless of input type. For every use case category present in the feature, generate at minimum the TC types listed below. The source may add scenarios beyond these — generate those too. But matrix entries are mandatory whenever their conditions apply, even if the source never enumerates them.

The matrix exists because FRS authors describe behaviour, not exhaustive validation surface, and the same blind spots appear over and over in QA reviews — duplicate, max-length, required, format, modal dismissal patterns, read-only enforcement, cross-field rules, state transitions, multi-tenancy, concurrency, session edge cases. They're almost always implicit in the data model or operation type.

How to apply the matrix: For each requirement and each FRS section processed in the walkthrough, identify which categories the operation touches (Create, Update, Display, View/Modal, State Change…). Then walk the matrix rows for those categories and generate one TC per applicable row.

Display / List

View / Preview / Modal Detail (read-only views and dialogs)

This category covers any operation that opens a modal, dialog, or detail view to display information without editing. Drives test plans like FRS-VP-01.

Create / Add

Update / Edit

Delete

State / Workflow Transitions

For entities with a status, state, or workflow stage. Drives plans for approval workflows, order lifecycles, document states.

Toggle / State change

Reorder / Sort

Search / Filter

Export / Download

Bulk Operations

Multi-Tenancy (ABP IMultiTenant entities)

Session / Authentication Lifecycle

Notifications (when present per FRS §14)

The matrix is the floor, not the ceiling. The source may add scenarios beyond these — generate those too. But never skip a matrix entry whose conditions apply by saying "the FRS doesn't mention it" — the matrix is what the source leaves implicit.

Overview

Use this skill when a QA engineer provides an FRS document (.md, .docx, .pdf, or pasted text) or source code files / a directory and asks for a test plan. The skill produces individual TC files in the docs/wiki repo, organized by feature and use case category, covering:

1. Every FRS section that produces TCs (Section Walkthrough)
2. Every applicable Required Coverage Matrix row
3. Every source-driven scenario from raw code (when applicable)

Every TC traces to its source — FR-ID, AC-ID, BR-ID, EC-ID, exception flow ID, or matrix row — so the resulting plan is auditable section by section.

Core principle: One flow variant = one TC file. One use case category = one sub-folder. Never mix unrelated actions in a single TC. Always cover the matrix floor and the section walkthrough before considering the plan complete.

Anti-Pattern: "I Can Guess the Selector"

When reading an FRS that says "Agent dismisses the modal", it is tempting to emit `[data-testid="btn-close-modal"]` because it seems obvious. Don't. The FRS describes behaviour, not markup. Guessed selectors cause silent test failures. Leave them as (discovered by explorer) and let the explorer skill resolve them against the real DOM.

Anti-Pattern: "I'll Just Write Files Wherever"

When the docs/wiki repo isn't immediately at ../docs/, it is tempting to fall back to a ./docs/ folder inside the current UI or API repo, or to write into the user's home directory. Don't. TC files belong in the docs/wiki repo, full stop. Run the discovery cascade in Step 1 and, if it fails, ask the user.

Anti-Pattern: "The FRS Didn't Mention It So I Won't Test It"

When the FRS describes only the happy path for "Add Service Type" — Name, Code, Description fields, Save button, success toast — it is tempting to emit only a happy-path TC. Don't. The data model implies a validation surface the FRS leaves unstated:

• Name and Code are almost certainly required → required-field TCs
• Name, Code, Description almost certainly have length caps → max-length TCs
• Code is almost certainly unique → duplicate TC
• Only authorized users can create → authorization TC
• The entity is IMultiTenant → cross-tenant isolation TCs

The Required Coverage Matrix is what the FRS forgets. Generate the matrix entries even when no requirement statement maps directly to them.

Anti-Pattern: "It's Just a View, How Many TCs Could There Be?"

Read-only modal/preview operations look small at first glance — the FRS has a few FRs about showing two images, a couple of exception flows, and that's it. In reality, a single read-only modal needs around 10–18 TCs once the matrix is walked: trigger, content correctness, labelling, read-only enforcement (FRs that say "shall NOT allow editing" need explicit absence assertions), three or four dismissal paths (close button, ESC, backdrop click, browser back), re-open behaviour, multi-target leakage, missing data placeholders, partial data, unauthorized target, session expiry during view. The View / Preview / Modal Detail matrix category exists because this surface gets under-tested every time it's not made explicit.

Anti-Pattern: "FR-04 Is Already in the Main Flow Somehow"

FRs that assert negative properties — "SHALL be read-only", "SHALL contain no input fields", "SHALL NOT allow annotation" — are NOT covered by the Main Flow TC. The Main Flow demonstrates that the system does something; the negative FR demonstrates the system does not do something else. These need their own dedicated TC that explicitly asserts absence (no editable fields, no submit buttons, no annotation tools, etc.). Trace the negative FR to that dedicated guard TC, not to the happy path.

Anti-Pattern: "The Open Question Is Probably X, Let's Just Use That"

If the FRS has an Open Question (typically Section 22, e.g. "For document verification rows, what are the two specific images displayed?"), do NOT invent the answer. Emit any dependent TC with the title prefixed PENDING — OQ-NN — and Postconditions noting the OQ. The TC stays as a placeholder so it isn't forgotten when the OQ resolves. Inventing answers produces TCs that test something the system was never specced to do.

When to Use

Use when:

• A QA engineer provides an FRS document and asks for a test plan
• A QA engineer points to raw source code (components, pages, API routes) and asks for a test plan
• A QA engineer provides a mix of FRS + code and asks for a test plan
• A QA engineer wants a test plan for a new requirement that will be tested via UI / E2E

Do NOT use when:

• Input is user stories or acceptance criteria → use skill:generate-test-plan-from-stories instead
• User wants to update selectors in existing TCs → use updateSelector operation
• User wants to run or execute tests → different workflow entirely

Checklist

You MUST complete these in order:

1. Locate the docs/wiki repo — run the discovery cascade (sibling → grandparent → ask) and record {docs_repo}
2. Classify input — determine FRS, raw code, or mixed
3. Identify feature name — derive the kebab-case feature name
4. Extract — three parallel outputs: (a) Section-walkthrough TC list (FRS only); (b) Source-driven requirement list; (c) Data-model fact sheet
5. Identify use case categories — determine the sub-folders (display, view, add, edit, delete, etc.)
6. Group into TCs per category — three passes: Pass 0 from the Section Walkthrough; Pass 1 from source-driven requirements; Pass 2 from the Required Coverage Matrix. Dedup across passes by attaching extra trace IDs to existing TCs rather than duplicating.
7. Generate Test Data per TC — populate ### Pre-existing State and ### Form Input sub-sections per references/test-data-generation.md, derived from the data-model fact sheet and the TC's matrix intent
8. Derive steps per TC — write Step / Selector / Expected Result rows
9. Resolve selectors (code input only) — scan source for data-testid, id, name, aria-label
10. Emit TC files — create each file under the correct sub-folder in {docs_repo}/test-plans/
11. Print summary — show a table grouped by use case, including any skipped files, matrix coverage, and FR/AC/BR/EC traceability coverage

Process Flow

digraph process {
    rankdir=TB;

    locate [label="Locate docs/wiki repo\n(sibling → grandparent → ask)" shape=diamond];
    classify [label="Classify input\n(FRS / code / mixed)" shape=diamond];
    extract [label="Step 4 — three outputs:\n(a) Section walkthrough TCs (FRS)\n(b) Source-driven requirements\n(c) Data-model fact sheet" shape=box];
    categories [label="Identify use case\ncategories (sub-folders)" shape=box];
    pass0 [label="Pass 0: Walk the FRS\nsection walkthrough" shape=box];
    pass1 [label="Pass 1: Source-driven TCs\n(from FRS REQs / code branches)" shape=box];
    pass2 [label="Pass 2: Walk the Required\nCoverage Matrix" shape=box];
    dedup [label="Dedup across passes\n(merge trace IDs)" shape=box];
    steps [label="Derive steps\nper TC" shape=box];
    selectors [label="Resolve selectors\nfrom code (code/mixed only)" shape=box];
    emit [label="Emit TC files under\n{docs_repo}/test-plans/{feature}/{use-case}/" shape=box];
    summary [label="Print summary table\n(created + skipped + matrix coverage\n+ FR/AC traceability coverage)" shape=doublecircle];

    locate -> classify -> extract -> categories;
    categories -> pass0 -> pass1 -> pass2 -> dedup;
    dedup -> steps -> selectors -> emit -> summary;
}

The Process

Step 1: Locate the Docs/Wiki Repo

The TC files must land in the docs/wiki repo, not inside the UI or API repo. Resolve the path in this order — stop at the first match:

1a. Check the conventional sibling path. Test ../docs/ relative to the current working directory. If it exists and contains .git/ (or a test-plans/ directory from a prior run), accept it.

1b. Scan for sibling repos with conventional names. From the parent of the current working directory, list immediate subdirectories and match any of: docs, wiki, knowledge, kb, documentation (case-insensitive). Prefer ones that contain .git/ over plain folders. If exactly one match: accept it. If multiple matches: list them and ask the user which one.

1c. Walk up one more level. If the current repo is nested (e.g. workspace/frontend/ui/), check the grandparent for the same name patterns as 1b, with the same .git/ preference and same ambiguity rule.

1d. Ask the user. If 1a–1c all fail, stop and ask:

"I couldn't find a docs/wiki repo near here. Where should I write the TC files? (e.g. ../docs, ~/work/wiki, or an absolute path)"

Once the user replies, validate the path exists and is writable before proceeding.

Record the resolved base path as {docs_repo}. All subsequent file operations write to {docs_repo}/test-plans/....

• Verify: {docs_repo} exists, is a directory, is writable, and is outside the current UI/API repo.
• On failure: Do not fall back to writing inside the current repo. Stop and ask.

Step 2: Classify Input

• Document (FRS, SRS, requirements doc): mode = frs
• Source code files or directory: mode = code
• Both provided: mode = mixed (FRS drives the section walkthrough, code provides selectors and supplements implicit behaviour)
• Verify: You can name the mode and list every input file/section.
• On failure: Ask the user to clarify what they provided.

Step 3: Identify Feature Name

• Derive a kebab-case feature name from the FRS title or module name.
  • FRS "Service Type Management" → service-type
  • FRS "Preview Verification Images Side-by-Side" (FRS-VP-01) → verification-preview
• Verify: Feature name is kebab-case, module title is human-readable.
• On failure: Ask the user to confirm.

Step 4: Extract — Three Parallel Outputs

This step produces three outputs that feed Step 6's three passes.

(a) Section-walkthrough TC list (FRS only)

For each FRS section in the FRS Section Walkthrough above, walk the section and record candidate TCs with their trace IDs. The output is a structured list:

Section walkthrough TCs (FRS-VP-01):
  Trigger + Main Flow:
    - TC-cand-A: Preview face row — Happy Path  [trace: FR-01, FR-02, FR-03, AC-01, AC-02]
  Alternative Flows:
    - 11a Face Verification Row Preview → consolidates with TC-cand-A
  Exception Flows:
    - TC-cand-B: Image retrieval failure — capture missing  [trace: EX-12a, FR-04, EC-01]
    - TC-cand-C: Image retrieval failure — reference missing  [trace: EX-12a, FR-04, EC-02]
    - TC-cand-D: Unauthorized session access  [trace: EX-12b, BR-01]
    - TC-cand-E: Session expired during preview  [trace: EX-12c]
  Functional Requirements (gap-fill — FRs not yet covered):
    - FR-02 (exactly two images, labelled): partly covered by A; emit dedicated assertion TC-cand-F
    - FR-05 (read-only — no input fields, no annotation, no submission): NOT covered → TC-cand-G
    - FR-06 (modal dismissible, table state restored): partly covered by A; emit dedicated dismissal TC-cand-H
  Acceptance Criteria (gap-fill):
    - AC-04 (dismissal restores table state): mapped to TC-cand-H
    - AC-05 (no input fields / submission controls): mapped to TC-cand-G
  Business Rules (gap-fill):
    - BR-04 (consistent labelling across row types): NOT covered → TC-cand-I
  Edge Cases (gap-fill):
    - EC-03 (document row preview): depends on OQ-01 → PENDING TC-cand-J
  Notifications: None — skip
  Form Fields: None — skip
  Out of scope: capture, decision recording, reference-photo management → no TCs; consider one Guard TC if absence is verifiable

…(truncated)