UKHO.GitHubCopilot.ToolKit work-packages.instructions.md

Work package documentation instructions

Overview

These instructions define how to document each incremental unit of work so it can be delivered iteratively and reviewed consistently. They are for contributors creating or updating work items under ./docs/.

Scope

These rules apply when adding or updating documentation for a unit of work. They are primarily concerned with content under ./docs/00x-work/.

Instructions

MUST

• You MUST maintain a project-level business requirements document at ./docs/business-requirements.md.

  • This document defines the business context, desired outcomes, and high-level requirements for the overall initiative.
  • It is the foundation upon which systems analysis and work packages are defined.

• You MUST NOT draft a new ./docs/00x-work/ work package unless the user or task explicitly requests one.

• You MUST maintain a project-level systems analysis document at ./docs/systems-analysis.md before commencing any work packages.

  • This document refines the business requirements into system boundary/context, use cases, business rules, analysis-level requirements, and quality attributes.
  • It must remain implementation-agnostic and must not replace per-work-package requirements/specification/plan documents.

• You MUST review the relevant ./docs/wiki/ pages before creating or updating work-package requirements, technical specifications, plans, review reports, or execution status so the work stays grounded in the current project understanding.

• You MUST create a dedicated folder under ./docs/ for each unit of work, named 00x-work where 00x is a zero-padded sequence number (e.g. 001) and work is a brief description of the task (for example: 001-add-order-endpoint).

• You MUST include a requirements.md in each ./docs/00x-work/ folder.

• You MUST ensure each work package requirements.md aligns with and links to ../business-requirements.md.

• You MUST produce a technical specification from the requirements and store it as technical-specification.md in the same ./docs/00x-work/ folder.

• You MUST create a plans/ subfolder inside each ./docs/00x-work/ folder when that work package needs one or more plans.

• You MUST create the initial delivery plan based on both the requirements and technical specification and store it as plans/001-delivery-plan.md in the same work-package folder.

• You MUST store any additional work-package plan documents in that same plans/ subfolder and name them with the next zero-padded sequence prefix (for example plans/002-some-refactor-plan.md).

• Work package requirements.md documents MUST remain implementation-agnostic.

  • Refer to a data store for configuration rather than naming SQL Server directly in requirements-level documents.

• You MUST keep the 00x number monotonically increasing (do not reuse a prior number for a different work item).

• You MUST keep each work item's documentation self-contained within its ./docs/00x-work/ folder and its plans/ subfolder.

• You MUST update the relevant documentation under ./docs/wiki/ before marking any numbered plan complete when the implemented behavior, architecture, API surface, runtime behavior, operator workflow, local development guidance, or testing approach has changed.

• When asked to review a work package, you MUST create the review report as a physical markdown file within that work package, not only as chat output.

• When creating a delivery plan from refactoring advice, you MUST scope the plan to that refactor objective rather than to existing work-package docs unless explicitly instructed to reuse them.