satellite-provider/_docs/02_tasks/todo/AZ-495_doc_folder_convention.md

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.