|
| 1 | +# BUILD_PR_LEVEL_21_2_TOOL_TESTING_DOCUMENTATION_AND_REPORT_STANDARDIZATION |
| 2 | + |
| 3 | +## Purpose |
| 4 | +Execute the first Tools roadmap testing lane by completing the documentation and reporting work that can be finished cleanly in one PR: |
| 5 | + |
| 6 | +- create full testing documentation for each tool |
| 7 | +- define manual test cases per tool |
| 8 | +- standardize validation reports under `docs/dev/reports` |
| 9 | + |
| 10 | +This PR does **not** attempt to complete automated validation. That remains the next lane. |
| 11 | + |
| 12 | +## Roadmap intent |
| 13 | +This PR may advance the following items only if fully executed and validated: |
| 14 | + |
| 15 | +- `create full testing documentation for each tool` `[ ] -> [x]` |
| 16 | +- `define manual test cases per tool` `[ ] -> [x]` |
| 17 | +- `standardize validation reports under docs/dev/reports` `[ ] -> [x]` |
| 18 | + |
| 19 | +Do **not** advance: |
| 20 | +- `add automated validation where possible` |
| 21 | + |
| 22 | +unless that work is actually completed in this same PR. |
| 23 | + |
| 24 | +## Scope |
| 25 | +Included: |
| 26 | +- inventory active tools |
| 27 | +- create or normalize a full testing document for each active tool |
| 28 | +- add manual test cases per tool |
| 29 | +- standardize validation report structure under `docs/dev/reports` |
| 30 | +- add a reusable report template for tool validation |
| 31 | +- update tool doc navigation where needed |
| 32 | +- preserve unrelated working-tree changes |
| 33 | + |
| 34 | +Excluded: |
| 35 | +- no feature work |
| 36 | +- no runtime changes unless strictly required for test harness discovery |
| 37 | +- no broad repo cleanup |
| 38 | +- no roadmap rewrites |
| 39 | +- no `start_of_day` changes |
| 40 | +- no speculative automation work beyond documenting automation opportunities |
| 41 | + |
| 42 | +## Active tools baseline |
| 43 | +Ensure the tools set explicitly includes current active tool surfaces, including: |
| 44 | +- Tile Map Editor |
| 45 | +- Parallax Editor |
| 46 | +- Vector Map Editor |
| 47 | +- Vector Asset Studio |
| 48 | + |
| 49 | +If additional active tools are present in the repo and are clearly in-scope, include them in the testing-doc set and record them in the inventory. |
| 50 | + |
| 51 | +## Required outputs |
| 52 | +Codex must create/update: |
| 53 | + |
| 54 | +- `docs/dev/reports/BUILD_PR_LEVEL_21_2_TOOL_TESTING_DOCUMENTATION_AND_REPORT_STANDARDIZATION_TOOL_INVENTORY.md` |
| 55 | +- `docs/dev/reports/BUILD_PR_LEVEL_21_2_TOOL_TESTING_DOCUMENTATION_AND_REPORT_STANDARDIZATION_VALIDATION.md` |
| 56 | +- `docs/dev/reports/tool_validation_report_template.md` |
| 57 | + |
| 58 | +Per-tool testing docs under a consistent location, for example: |
| 59 | +- `docs/tools/<tool-name>/testing.md` |
| 60 | +or the current tool-doc structure if already established and coherent |
| 61 | + |
| 62 | +Each per-tool testing doc must contain: |
| 63 | +- purpose of testing |
| 64 | +- prerequisites |
| 65 | +- setup steps |
| 66 | +- smoke tests |
| 67 | +- core workflow tests |
| 68 | +- edge case tests |
| 69 | +- regression checks |
| 70 | +- known limitations / non-goals |
| 71 | +- expected validation artifacts |
| 72 | + |
| 73 | +## Manual test-case requirements |
| 74 | +Each active tool must have explicit manual test cases covering: |
| 75 | +- launch / boot |
| 76 | +- open/load workflow |
| 77 | +- create/edit workflow |
| 78 | +- save/export workflow if applicable |
| 79 | +- invalid input / error handling |
| 80 | +- UI persistence or state restoration if applicable |
| 81 | +- integration handoff to repo/runtime where applicable |
| 82 | + |
| 83 | +## Validation report standardization requirements |
| 84 | +Create or normalize a common validation report shape that includes: |
| 85 | +- tool name |
| 86 | +- date / run context |
| 87 | +- environment |
| 88 | +- cases executed |
| 89 | +- pass/fail per case |
| 90 | +- blockers |
| 91 | +- screenshots or artifact references if applicable |
| 92 | +- summary / recommendation |
| 93 | + |
| 94 | +## Acceptance |
| 95 | +- every active tool has a testing document |
| 96 | +- every active tool has manual test cases |
| 97 | +- validation reporting format is standardized under `docs/dev/reports` |
| 98 | +- tool inventory is explicit and current |
| 99 | +- no unrelated repo churn |
| 100 | +- roadmap updates are status-only and execution-backed |
| 101 | + |
| 102 | +## Validation requirements |
| 103 | +Validation must confirm: |
| 104 | +- active tools inventory is complete |
| 105 | +- testing doc exists for every active tool |
| 106 | +- manual cases exist for every active tool |
| 107 | +- validation template exists and is reusable |
| 108 | +- no `start_of_day` changes |
| 109 | +- unrelated working-tree changes preserved |
| 110 | + |
| 111 | +## Roadmap update rules |
| 112 | +Only update status markers in: |
| 113 | +- `docs/dev/roadmaps/MASTER_ROADMAP_TOOLS.md` |
| 114 | + |
| 115 | +Allowed transitions only if fully executed and validated: |
| 116 | +- `create full testing documentation for each tool` `[ ] -> [x]` |
| 117 | +- `define manual test cases per tool` `[ ] -> [x]` |
| 118 | +- `standardize validation reports under docs/dev/reports` `[ ] -> [x]` |
| 119 | + |
| 120 | +Do not update: |
| 121 | +- `add automated validation where possible` |
0 commit comments