satellite-provider/.cursor/skills/plan/steps/01_artifact-management.md

Artifact Management

Directory Structure

All artifacts are written directly under DOCUMENT_DIR:

DOCUMENT_DIR/
├── tests/
│   ├── environment.md
│   ├── test-data.md
│   ├── blackbox-tests.md
│   ├── performance-tests.md
│   ├── resilience-tests.md
│   ├── security-tests.md
│   ├── resource-limit-tests.md
│   └── traceability-matrix.md
├── architecture.md
├── system-flows.md
├── data_model.md
├── deployment/
│   ├── containerization.md
│   ├── ci_cd_pipeline.md
│   ├── environment_strategy.md
│   ├── observability.md
│   └── deployment_procedures.md
├── risk_mitigations.md
├── risk_mitigations_02.md          (iterative, ## as sequence)
├── adr/
│   ├── 001_[decision_slug].md
│   ├── 002_[decision_slug].md
│   └── ...
├── components/
│   ├── 01_[name]/
│   │   ├── description.md
│   │   └── tests.md
│   ├── 02_[name]/
│   │   ├── description.md
│   │   └── tests.md
│   └── ...
├── common-helpers/
│   ├── 01_helper_[name]/
│   ├── 02_helper_[name]/
│   └── ...
├── diagrams/
│   ├── components.drawio
│   └── flows/
│       ├── flow_[name].md          (Mermaid)
│       └── ...
└── FINAL_report.md

Save Timing

Step	Save immediately after	Filename
Step 1	Blackbox test environment spec	tests/environment.md
Step 1	Blackbox test data spec	tests/test-data.md
Step 1	Blackbox tests	tests/blackbox-tests.md
Step 1	Blackbox performance tests	tests/performance-tests.md
Step 1	Blackbox resilience tests	tests/resilience-tests.md
Step 1	Blackbox security tests	tests/security-tests.md
Step 1	Blackbox resource limit tests	tests/resource-limit-tests.md
Step 1	Blackbox traceability matrix	tests/traceability-matrix.md
Step 2	Architecture analysis complete	architecture.md
Step 2	System flows documented	system-flows.md
Step 2	Data model documented	data_model.md
Step 2	Deployment plan complete	deployment/ (5 files)
Step 3	Each component analyzed	components/[##]_[name]/description.md
Step 3	Common helpers generated	common-helpers/[##]_helper_[name].md
Step 3	Diagrams generated	diagrams/
Step 4	Risk assessment complete	risk_mitigations.md
Step 4.5	Each ADR captured	adr/NNN_[decision_slug].md
Step 4.5	ADR index updated	adr/README.md
Step 5	Tests written per component	components/[##]_[name]/tests.md
Step 6	Epics created in work item tracker	Tracker via MCP
Final	All steps complete	FINAL_report.md

Save Principles

1. Save immediately: write to disk as soon as a step completes; do not wait until the end
2. Incremental updates: same file can be updated multiple times; append or replace
3. Preserve process: keep all intermediate files even after integration into final report
4. Enable recovery: if interrupted, resume from the last saved artifact (see Resumability)

Resumability

If DOCUMENT_DIR already contains artifacts:

1. List existing files and match them to the save timing table above
2. Identify the last completed step based on which artifacts exist
3. Resume from the next incomplete step
4. Inform the user which steps are being skipped

Step 4.5 (ADR Capture) resumption rule

ADR files have a Status field that disambiguates "step in progress" from "step done":

• Status: Proposed → Step 4.5 is in progress. The user has not yet hit the BLOCKING gate (or hit it and chose B/C/D, which kept files at Proposed). Resume Step 4.5 at Phase 4.5f and re-present the BLOCKING Choose to the user. Do NOT skip to Step 5.
• Status: Accepted AND adr/README.md index exists AND every Accepted ADR is referenced in the index → Step 4.5 is done. Skip to Step 5.
• Status: Accepted but adr/README.md is missing or out of date → Step 4.5 is partially complete. Resume at Phase 4.5d (Maintain the ADR Index) before moving on.
• Mixed Proposed + Accepted files in the same directory → Step 4.5 is in progress with prior partial confirmations. Resume at Phase 4.5f and re-present only the still-Proposed ADRs.
• Empty adr/ directory or no adr/ directory → Step 4.5 has not started yet. Begin at Phase 4.5a.

The Date field on every Accepted ADR is the date the user confirmed it; do not regenerate it during resumption.