# 00. Directory Structure & File Naming Convention

## Objective

Define and standardize directory organization and file naming rules for all Artifacts generated in the QA Workflow. Ensures consistency, traceability, and maintainability across the project.

> **Important**: This document is the **mandatory reference** for the entire workflow. All generated Artifacts (QnA Log, Test Plan, TestCase, Review Result, Dev Checklist) must strictly follow the rules defined here before executing any step in the workflow.

---

## 1. Directory Overview

```text
AK-Docs/03.Testing/
├── 00.Strategies/
│   └── Test-Strategy.md                     ← project-level, Gate 1 Step 0.7
└── 01.Testcases/
    └── [functionId]/
        ├── [functionId]_QnA Log.md          ← Gate 1–4 (all questions, answers, decisions)
        ├── [functionId]_Test Plan.md        ← Gate 1 (Part 1), Gate 2 (Part 2), Gate 3 (Part 3)
        ├── [functionId]_TestCase.md         ← Gate 3 (built by `ak tc build`), Gate 4 Edits only
        ├── [functionId]_Review Result.md    ← Gate 4
        ├── [functionId]_Dev_Checklist.md    ← Gate 4
        └── _parts/                          ← temporary, Gate 3 only — removed by `ak tc build`
```

Example: `functionId = AD06` → root folder is `AK-Docs/03.Testing/`

> `create-testcase` no longer writes anything to `AK-Docs/03.Testing/07.AI-Artifacts/`. No other workflow writes there either.

> ⚠️ **Path rule (mandatory):** `AK-Docs/` is the sibling folder at the workspace root (next to the source repo). Every path in this document lives **inside** `AK-Docs/` — always write files using the full `AK-Docs/03.Testing/...` path. **Never** create a `03.Testing/` folder at the workspace root or inside the source repo.

> File names contain spaces (`QnA Log`, `Test Plan`, `Review Result`) → always quote the path in shell commands, e.g. `ak tc lint --doc "AK-Docs/03.Testing/01.Testcases/AD06/AD06_Test Plan.md"`.

---

## 2. 01.Testcases/[functionId]/ Directory Rules

- **Root path**: `AK-Docs/03.Testing/01.Testcases/[functionId]/`
- **Purpose**: Store every artifact of the `create-testcase` workflow for one functionId — analysis, questions, scenarios, coverage, the test case set, the review result and the Dev self-check checklist.

### 2.1. File Name Table by Gate

| File | Written by | Template |
| :--- | :--- | :--- |
| `[functionId]_QnA Log.md` | Gate 1–4 (only when there are questions) | `.claude/skills/ba-skills/skill-ba-qna-template-v1.md` — question IDs `TQ-xx`, severity 🔴 Blocking / 🟡 Non-blocking |
| `[functionId]_Test Plan.md` | Gate 1 Part 1 (Analysis), Gate 2 Part 2 (Scenario), Gate 3 Part 3 (Coverage) | `.claude/skills/test-skills/template/test-plan-template.md` |
| `[functionId]_TestCase.md` | Gate 3 (`ak tc build`), Gate 4 (Edit TCs with findings) | `.claude/skills/test-skills/template/testcase-template.md` |
| `[functionId]_Review Result.md` | Gate 4 | `.claude/skills/test-skills/template/review-result-template.md` |
| `[functionId]_Dev_Checklist.md` | Gate 4 | `.claude/skills/test-skills/template/dev-checklist-template.md` |

Open points are marked `[PENDING - TQ-xx]` in the Test Plan / TestCase, pointing to the question in the QnA Log.

### 2.2. Full Path Examples

```
AK-Docs/03.Testing/01.Testcases/AD06/AD06_QnA Log.md
AK-Docs/03.Testing/01.Testcases/AD06/AD06_Test Plan.md
AK-Docs/03.Testing/01.Testcases/AD06/AD06_TestCase.md
AK-Docs/03.Testing/01.Testcases/AD06/AD06_Review Result.md
AK-Docs/03.Testing/01.Testcases/AD06/AD06_Dev_Checklist.md
```

### 2.3. `_parts/` (temporary, Gate 3)

- **Path**: `AK-Docs/03.Testing/01.Testcases/[functionId]/_parts/`
- `gate3-brief.md` — shared brief for the `tc-writer` agents (template `.claude/skills/test-skills/template/gate3-brief-template.md`).
- `03_part-<section>.md` — one part file per section (or per screen/field when a section is large). First line is mandatory: `<!-- ak-part: section=<n> range=<first ID>..<last ID> -->`.
- `ak tc build` assembles the parts into `[functionId]_TestCase.md` and removes `_parts/` on success. On error the parts are kept — fix the failing part and rerun; never hand-edit `TestCase.md` to get past a build error.

### 2.4. TestCase File Content

The TestCase file follows the **standard template** at `.claude/skills/test-skills/template/testcase-template.md` and **only includes**:

- **Section 1**: General Information (functionId, `UC-Spec-Version`, `System-Requirement-Version`, `Test-Strategy-Version`)
- **Section 2**: Test Execution Summary (reset to 0, waiting for execution)
- **Section 3**: Detailed Test Cases (all 5 groups and test case tables)

> **Does NOT include**: Review Summary, Findings, Coverage Validation, RTM, Sign-off Status — these belong in `[functionId]_Review Result.md`. The Coverage Matrix belongs in `[functionId]_Test Plan.md` Part 3.

### 2.5. Generation Timing

The test case set is written **once**: Gate 3 writes the part files and `ak tc build` assembles `[functionId]_TestCase.md`. Gate 4 only Edits the TCs with findings — it never rewrites or copies the set, not even into `Review Result.md`.

### 2.6. Dev Checklist File

`[functionId]_Dev_Checklist.md` is the self-check list Dev runs **before** handing the feature over to QA. It follows the template at `.claude/skills/test-skills/template/dev-checklist-template.md`.

**Checklist ID convention:**

```
<FE|BE>-<functionId>-<3 digits>
```

Valid examples: `FE-AD06-001`, `BE-AD06-001`, `FE-WONDER-1035-012`.
Sequence numbers run independently for FE and BE, start at `001`, and stay continuous within a section — they do not reset per group.

**Content rules:**

- Every row is taken from **one** test case in `[functionId]_TestCase.md`; that Test Case ID goes in the `TC ID` column. No row without a `TC ID`.
- Columns: `ID | Checklist Name | Expected Result | Result | Note | TC ID`. `Result` and `Note` ship empty — Dev fills them in while running.
- Both the FE and the BE section carry the same 5 groups: Happy case · Basic validation · Task-specific requirements · API cases · Exception cases.
- A section or group with no matching test case keeps its heading and states `N/A — <reason>`.

**Version rule:** one file per functionId, overwritten in place, exactly like `[functionId]_TestCase.md`. No version suffix in the file name — history lives in git. On Mode UPDATE, rows whose `TC ID` no longer exists in the new test case set are **removed**.

**Linting:** `ak tc lint --checklist AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Dev_Checklist.md` — zero `error` before Gate 4 sign-off.

---

## 3. Full Artifact Matrix

| Gate | Description | Output |
| :---: | :--- | :--- |
| **01** | Analysis & Q&A | `[fId]_Test Plan.md` (General Info + Part 1), `[fId]_QnA Log.md` |
| **02** | Test Plan (Scenario Building) | `[fId]_Test Plan.md` (Part 2), `[fId]_QnA Log.md` (new questions only) |
| **03** | Test case creation | `_parts/` (temporary) → `[fId]_TestCase.md` (`ak tc build`), `[fId]_Test Plan.md` (Part 3), `[fId]_QnA Log.md` (new questions only) |
| **04** | Review (user review, AI Edit) | Edit `[fId]_TestCase.md`, `[fId]_Review Result.md`, `[fId]_Dev_Checklist.md`, `[fId]_QnA Log.md` (new questions only) |

> `[fId]` = `[functionId]`

---

## 4. Additional Rules

### 4.1. Update Rule

- If a file already exists, **update and overwrite** with the latest content (Mode UPDATE: Test Plan and QnA Log are updated in place; `ak tc build --base` keeps carry-forward TCs).
- **Do not create duplicate files** with version suffixes (e.g. `_v1`, `_v2`, `_final`, `_new`).

### 4.2. functionId Naming

- Use the **exact functionId** determined in Gate 1 Pre-flight (e.g. `AD06`, `AD10`, `LOGIN`).
- Valid examples: `AD06`, `AD10_Create_Product`, `LOGIN`, `ORD002`
- **Invalid**: `product`, `login`, `tag_feature` (custom names diverging from the functionId)
- The workflow **MUST** strictly require a `functionId` before starting.

### 4.3. Consistency Principle

- All artifacts for the same functionId **must use the same functionId prefix** and live in the same `01.Testcases/[functionId]/` subfolder.
- This ensures fast cross-lookup and traceability.

---

## 5. Application Checklist

Before starting any workflow gate, verify:

- [ ] functionId has been confirmed in Gate 1 Pre-flight?
- [ ] Root folder `AK-Docs/03.Testing/` exists (inside `AK-Docs/`, not a `03.Testing/` at the workspace root)?
- [ ] `AK-Docs/03.Testing/01.Testcases/[functionId]/` subfolder exists?
- [ ] File names follow the table in §2.1 (`[functionId]_QnA Log.md`, `[functionId]_Test Plan.md`, `[functionId]_TestCase.md`, `[functionId]_Review Result.md`, `[functionId]_Dev_Checklist.md`)?
- [ ] Nothing written to `AK-Docs/03.Testing/07.AI-Artifacts/`?
- [ ] (After Gate 3) `[functionId]_TestCase.md` built by `ak tc build` and `_parts/` removed?
- [ ] (After Gate 3) TestCase file contains only Section 1+2+3 per template (no review metadata)?
- [ ] No duplicate or incorrectly named files?

---

## 6. References

- `create-testcase-workflow.md` — Full 4-Gate QA workflow definition
- `.claude/skills/test-skills/template/testcase-template.md` — Standard test case template
- `.claude/skills/test-skills/template/test-plan-template.md` — Test Plan template
- `.claude/skills/test-skills/template/review-result-template.md` — Review Result template
- `.claude/skills/test-skills/template/gate3-brief-template.md` — Gate 3 shared brief template
- `.claude/skills/ba-skills/skill-ba-qna-template-v1.md` — QnA Log template (shared with `create-spec`)
- `.claude/skills/test-skills/rules/qa-writing-standards.md` — QA writing standards
