mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-22 15:21:15 +00:00
[AZ-491] [AZ-492] [AZ-493] [AZ-494] [AZ-495] [AZ-496] Cycle 3 Step 9: 6 task specs
Drains the cycle-2 retrospective top-3 improvement actions plus three carried-forward security and process items, into 6 individually- trackable PBIs: - AZ-491 (3 SP) consolidate JWT test-mint helpers (Retro Action 1) - AZ-492 (3 SP) perf harness PT-07 + PT-08 + JWT-attach (Retro Act. 2) - AZ-493 (2 SP) integration test DB-reset hook (Retro Action 3) - AZ-494 (2 SP) JWT iss/aud validation (cycle-2 F-AUTH-2 Medium) - AZ-495 (1 SP) doc-folder convention for WebApi (cycle 1+2 F1 carry) - AZ-496 (2 SP) bump AspNetCore 8.0.21 -> 8.0.25 (cycle 1+2 D1+D3) All 6 at-or-below the user-rule 5 SP cap. AZ-494 gated on admin-team confirming iss/aud values. Cycle 3 total: 13 SP. Autodev pointer advances to Step 10 Implement. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,119 @@
|
||||
# Doc-folder convention for WebApi component
|
||||
|
||||
**Task**: AZ-495_doc_folder_convention
|
||||
**Name**: Resolve doc-folder convention for WebApi
|
||||
**Description**: Settle the recurring F1 code-review finding (cycle 1 AZ-487 + cycle 2 AZ-488) where task specs reference `_docs/02_document/components/01_web_api/description.md` which does not exist. Pick one: (a) create the stub folder, or (b) formalize the "WebApi lives in `modules/api_program.md`" convention. Update task-spec templates accordingly so the finding stops recurring.
|
||||
**Complexity**: 1 point
|
||||
**Dependencies**: None
|
||||
**Component**: Documentation conventions (`_docs/02_document/`) + task-spec templates (`.cursor/skills/decompose/templates/task.md`)
|
||||
**Tracker**: AZ-495
|
||||
**Epic**: none (process / quality)
|
||||
|
||||
## Problem
|
||||
|
||||
The cycle-1 (AZ-487) and cycle-2 (AZ-488) code reviews each surfaced an identical F1 finding (Low / Style): the task spec referenced `_docs/02_document/components/01_web_api/description.md`, a folder that has never existed in the codebase. The existing component-doc folders are:
|
||||
|
||||
```
|
||||
_docs/02_document/components/
|
||||
01_common/
|
||||
02_data_access/
|
||||
03_tile_downloader/
|
||||
04_region_processing/
|
||||
05_route_management/
|
||||
```
|
||||
|
||||
The WebApi component's documentation lives in `_docs/02_document/modules/api_program.md`. Each cycle's batch worked around the missing folder by updating `modules/api_program.md` instead. The decision item — create the stub folder OR formalize the modules-only convention — was carried as an open item but never settled.
|
||||
|
||||
The cycle-2 retrospective (`_docs/06_metrics/retro_2026-05-11_cycle2.md` § 9) lists this as a decision item carried over. Until it's settled, every future cycle that touches WebApi will repeat the same finding and the same workaround.
|
||||
|
||||
## Outcome
|
||||
|
||||
- The decision is made and reflected in `_docs/02_document/module-layout.md` (canonical convention).
|
||||
- Task-spec templates and any decompose-skill prompts that auto-generate task docs no longer reference a nonexistent path.
|
||||
- The cycle 1 + cycle 2 code-review findings (F1) are explicitly resolved with a back-reference to this PBI's tracker ID.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
|
||||
Option **A — Create stub folder** (matches the layout convention of other components):
|
||||
- Create `_docs/02_document/components/01_web_api/description.md` as a brief stub that:
|
||||
- Documents the WebApi component at a level consistent with the other 5 component descriptions (purpose, architectural pattern, upstream/downstream).
|
||||
- Either inlines the full content (preferred for consistency) or includes a single "for module-level detail, see `_docs/02_document/modules/api_program.md`" pointer.
|
||||
- Renumber existing components if needed (e.g., 01_common stays, WebApi becomes 06_web_api at the layer-4 position — implementer's call based on architecture layering).
|
||||
- Update task-spec templates to point at the new path.
|
||||
|
||||
Option **B — Formalize modules-only convention for WebApi**:
|
||||
- Update `_docs/02_document/module-layout.md` § "Documentation layout" with an explicit note: "The WebApi component (`SatelliteProvider.Api`) has no `components/*` folder — its documentation lives in `_docs/02_document/modules/api_program.md` because the API layer is documented at module-level rather than component-level."
|
||||
- Update task-spec templates and any decompose-skill scaffolds to reference `modules/api_program.md` instead of a nonexistent `components/01_web_api/description.md` path.
|
||||
- Add a checklist row to `.cursor/skills/new-task/SKILL.md` Step 4 (Codebase Analysis): "WebApi documentation is in `modules/api_program.md`, not `components/`."
|
||||
|
||||
Either option:
|
||||
- Update `_docs/03_implementation/reviews/batch_01_cycle2_review.md` and `batch_02_cycle2_review.md` with a one-line resolution note pointing at this PBI.
|
||||
- Update the cycle-2 retrospective decision-item list (§ 9) to mark F1 resolved.
|
||||
|
||||
### Excluded
|
||||
|
||||
- Rewriting any existing module documentation. The module-level `api_program.md` stays where it is; this PBI is about the convention, not the content.
|
||||
- Restructuring the other 5 component folders.
|
||||
- Changing the layout of `modules/` vs `components/` — that's a much larger decision.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
**AC-1: One option chosen and documented**
|
||||
Given the post-PBI repository
|
||||
When `_docs/02_document/module-layout.md` is read
|
||||
Then either (a) a `components/01_web_api/description.md` (or its renumbered equivalent) exists with non-trivial content, OR (b) an explicit "WebApi has no components/* folder" convention is documented with rationale.
|
||||
|
||||
**AC-2: Templates updated**
|
||||
Given a fresh `/new-task` invocation that touches WebApi
|
||||
When the skill generates a task spec
|
||||
Then the spec references the correct documentation location (Option A: the new component folder; Option B: `modules/api_program.md`) — never the nonexistent path.
|
||||
|
||||
**AC-3: Code-review findings explicitly resolved**
|
||||
Given the post-PBI repository
|
||||
When `_docs/03_implementation/reviews/batch_01_cycle2_review.md` and `batch_02_cycle2_review.md` are read
|
||||
Then their F1 finding sections include a resolution note pointing at this PBI.
|
||||
|
||||
**AC-4: Regression check**
|
||||
Given a hypothetical next cycle's code review
|
||||
When the review runs Phase 6 (Cross-Task Consistency)
|
||||
Then no F1-shaped finding fires because either the path now exists OR the convention is documented and templates were updated.
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
**Compatibility**
|
||||
- Must not break links from any existing documentation file. If Option A introduces a new path, run a grep for `01_web_api` across all `_docs/` files and confirm none reference a path that hasn't been created.
|
||||
- Must not break the existing `monorepo-document` skill workflow (which reads component descriptions).
|
||||
|
||||
## Unit Tests
|
||||
|
||||
| AC Ref | What to Test | Required Outcome |
|
||||
|--------|-------------|-----------------|
|
||||
| (none) | This is a documentation / convention PBI; no code paths to unit-test | — |
|
||||
|
||||
## Blackbox Tests
|
||||
|
||||
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|
||||
|--------|------------------------|-------------|-------------------|----------------|
|
||||
| AC-2 | Fresh `/new-task` invocation touching a WebApi-side change | The generated task spec's Documentation section | References the correct path; no reference to nonexistent path | — |
|
||||
|
||||
## Constraints
|
||||
|
||||
- The decision is binary — pick A or B, not "both" or "neither".
|
||||
- If Option A is chosen, the new file's content must be substantive enough to justify its existence (≥ 30 lines), not a one-line redirect placeholder.
|
||||
- If Option B is chosen, the convention note in `module-layout.md` must include the rationale, not just the rule.
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
**Risk 1: Decision deferred again**
|
||||
- *Risk*: This PBI ends up "let's revisit later" without picking A or B, and the F1 finding recurs in cycle 3.
|
||||
- *Mitigation*: The PBI is explicitly a forced decision. Implementer or operator picks A or B during the kickoff conversation; no third "deferred" option is acceptable.
|
||||
|
||||
**Risk 2: Renumbering ripples (Option A)**
|
||||
- *Risk*: If Option A inserts `01_web_api` and renumbers existing folders, all existing component-doc links across `_docs/` break.
|
||||
- *Mitigation*: Prefer appending (e.g., `06_web_api`) rather than renumbering. Run a grep for `components/0` references before/after to catch any broken link.
|
||||
|
||||
**Risk 3: Convention drift (Option B)**
|
||||
- *Risk*: Future developers see 5 `components/` folders and 1 module file and instinctively create a 6th `components/` folder for WebApi.
|
||||
- *Mitigation*: The note in `module-layout.md` is canonical. Add a checklist line to `new-task` skill so the agent surfaces the convention at task-creation time.
|
||||
Reference in New Issue
Block a user