---
name: fluent-archive
description: Archive completed or abandoned features. Updates status.json to ARCHIVED, generates an archive summary, and optionally cleans up ephemeral reports. Triggers on "archive feature", "archive this", "mark as archived", "close feature", "feature done".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: <feature-slug> [--profile PROFILE] [--reason completed|abandoned|superseded] [--cleanup] [--force]
cursor-tier: auto
---

# Feature Archival

Transition a feature to `ARCHIVED` status with proper audit trail, summary generation, and optional ephemeral cleanup. This is the complement to `/fluent-use-case-discover` (which creates features) — it retires them.

## Pre-flight: Feedback Check

Before starting, check for past learnings from this skill:

1. Check if `accounts/<PROFILE>/feedback/fluent-archive.jsonl` exists
2. If yes, read last 20 records
3. Filter to: FAILURE or USER_CORRECTED outcomes, confidence = CONFIRMED or PROMOTED
4. Extract top 3 relevant learnings — use as internal guidance during execution
5. Do NOT show raw feedback to the user — silently adjust approach based on past issues

## Ownership Boundary

This skill owns: status transition to ARCHIVED, archive summary generation, optional ephemeral report cleanup.

Other skills own: all other status transitions (`/fluent-use-case-discover` → DISCOVERY, `/fluent-feature-plan` → PLANNING, etc.), canonical feature files (spec.md, plan.md, architecture.md).

**Safety invariant:** This skill NEVER deletes `spec.md`, `plan.md`, `architecture.md`, or `status.json`. These are permanent project records.

## When to Use

- Feature has been verified and deployed to production → `--reason completed`
- Feature was cancelled or de-scoped → `--reason abandoned`
- Feature was replaced by a newer version → `--reason superseded`
- Cleaning up old features to keep `/fluent-feature-status` dashboard focused
- End of a project phase — bulk archive verified features

## Inputs

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `<feature-slug>` | Yes | -- | Feature slug (directory name under `features/`) |
| `--profile` | No | Active CLI profile | Fluent CLI profile |
| `--reason` | No | Auto-detected | Archive reason: `completed`, `abandoned`, `superseded` |
| `--cleanup` | No | `false` | Remove ephemeral reports related to this feature |
| `--force` | No | `false` | Allow archiving IN_PROGRESS features (normally blocked) |

## Execution Flow

### Phase 1: Pre-flight Checks

```
1. Resolve profile from --profile or active profile
2. Verify accounts/<PROFILE>/features/<slug>/ exists
3. Read status.json
4. Validate transition:
   VERIFIED → ARCHIVED       : ALLOWED (default reason: completed)
   DEPLOYED → ARCHIVED       : ALLOWED (default reason: completed or abandoned)
   BUILT → ARCHIVED          : ALLOWED (reason: abandoned or superseded required)
   APPROVED → ARCHIVED       : ALLOWED (reason: abandoned or superseded required)
   PLANNING → ARCHIVED       : ALLOWED (reason: abandoned)
   DISCOVERY → ARCHIVED      : ALLOWED (reason: abandoned)
   IN_PROGRESS → ARCHIVED    : BLOCKED unless --force
   ARCHIVED → ARCHIVED       : NO-OP, warn "Already archived"
```

### Phase 2: Reason Resolution

If `--reason` not specified, auto-detect:

| Current Status | Default Reason |
|---------------|----------------|
| VERIFIED | `completed` |
| DEPLOYED | `completed` |
| BUILT | `abandoned` |
| APPROVED | `abandoned` |
| PLANNING | `abandoned` |
| DISCOVERY | `abandoned` |
| IN_PROGRESS (with --force) | `abandoned` |

### Phase 3: Archive Execution

```
1. Read current status.json (full content)
   - Read `retailers` array if present; fall back to `retailer` (string) for backward compatibility

2. Update fields:
   {
     "status": "ARCHIVED",
     "updated": "<today>",
     "archivedOn": "<today>",
     "archiveReason": "<reason>",
     "next": null
   }

   Preserve the gate fields as-is — do NOT reset them:
   - `build` — keep existing value (`null`, `"PASSED"`, or `"FAILED"`)
   - `deploy` — keep existing value (`null`, `"DEPLOYED"`, or `"FAILED"`)
   - `test` — keep existing value (`null`, `"PASSED"`, or `"FAILED"`)
   These fields provide an audit record of how far the feature progressed before archival.

3. Write updated status.json

4. Generate archive-summary.md (companion file)
```

### Phase 4: Archive Summary Generation

Write `accounts/<PROFILE>/features/<slug>/archive-summary.md`:

```markdown
# Archive Summary: <feature-slug>

| Field | Value |
|-------|-------|
| Archived | 2026-02-25 |
| Reason | completed |
| Previous status | VERIFIED |
| Retailers | My Retailer |
| Spec | APPROVED |
| Plan | APPROVED (rev 2) |
| Architecture | Yes |
| Based On | home-delivery |

## Canonical Artifacts (preserved)
- spec.md (1,234 bytes)
- plan.md (5,678 bytes)
- architecture.md (3,456 bytes)
- status.json (updated to ARCHIVED)

## Related Reports
- reports/build/fc-module-curbside-2026-02-24.json
- reports/pre-deploy/curbside-2026-02-24.json
- reports/e2e-test/curbside-2026-02-25.json

## Sessions
- sessions/abc123.json
- sessions/def456.json
```

### Phase 5: Optional Cleanup (--cleanup)

When `--cleanup` is specified:

1. Scan `accounts/<PROFILE>/reports/` for files referencing this feature slug
2. List files that would be deleted and show to user
3. WAIT for user confirmation before deleting
4. Delete only ephemeral reports (build/, pre-deploy/, e2e-test/ files)
5. NEVER delete anything under `features/<slug>/` except ephemeral companions

**Protected files (NEVER delete):**
- `features/<slug>/spec.md`
- `features/<slug>/plan.md`
- `features/<slug>/architecture.md`
- `features/<slug>/status.json`
- `features/<slug>/archive-summary.md`
- `features/<slug>/history/*.md` (plan revision snapshots)
- `features/<slug>/assets/*` (screenshots, recordings, visual evidence)

## Safety Guards

1. **NEVER delete canonical files** — spec.md, plan.md, architecture.md, status.json are permanent
2. **NEVER archive IN_PROGRESS without --force** — active work may be lost
3. **ALWAYS read current status before updating** — prevent race conditions
4. **ALWAYS generate archive-summary.md** — ensures audit trail
5. **WARN if feature has unfinished scope tasks** — check `analysis/scope/` for matching task files with `status: "pending"`
6. **WARN if feature has basedOn references** — other features may depend on this one's architecture.md

## Blocked Scenarios

### IN_PROGRESS without --force
```
-> BLOCKED: Feature "order-return" is IN_PROGRESS.
  Active work may exist. To archive anyway, use --force.
  Consider: run /fluent-feature-status to check what's pending.
```

### Already archived
```
-> SKIP: Feature "old-feature" is already ARCHIVED (since 2026-02-20, reason: completed).
  No action taken.
```

### Feature directory not found
```
-> BLOCKED: Feature "nonexistent" not found.
  No directory at accounts/MY_PROFILE/features/nonexistent/
  Run /fluent-feature-status to see available features.
```

## Handoff Protocol

### Emitted Signals
- `-> READY: accounts/<PROFILE>/features/<slug>/archive-summary.md` -- Archive complete
- `-> BLOCKED: Feature is IN_PROGRESS` -- Cannot archive without --force
- `-> SKIP: Already archived` -- No action needed

### Consumed Signals
- Reads `status.json` from feature directory
- Reads `sessions` array to list related session exports

## Error Reporting

| Severity | Code | Scenario | Recovery |
|----------|------|----------|----------|
| CRITICAL | `WRITE_FAILED` | Cannot update status.json | Check file permissions |
| HIGH | `IN_PROGRESS_BLOCKED` | Feature is IN_PROGRESS | Use --force or complete the feature first |
| MEDIUM | `ORPHANED_REPORTS` | Reports exist but feature directory is missing | Manual cleanup needed |
| LOW | `ALREADY_ARCHIVED` | Feature is already ARCHIVED | No action needed |

## Session Tracking

When invoked, log:
```
SKILL: /fluent-archive
  args: <slug> --profile <PROFILE> --reason <reason> [--cleanup] [--force]
  outcome: completed | blocked | skipped
  previous_status: <status>
  archive_reason: completed | abandoned | superseded
  cleanup_performed: true | false
  files_cleaned: <count>
  artifacts_preserved: [spec.md, plan.md, architecture.md, status.json]
```

## Integration with Other Skills

| Skill | Relationship |
|-------|-------------|
| `/fluent-feature-status` | Shows features ready to archive (VERIFIED status) |
| `/fluent-use-case-discover` | Creates features — this skill retires them |
| `/fluent-session` | Session exports and audit trail for the archive |

## Reversibility

Archival is **reversible**. To restore a feature:

1. Edit `status.json` manually:
   - Set `status` back to previous state (e.g., `VERIFIED` or `APPROVED`)
   - Clear `archivedOn` and `archiveReason`
   - Set appropriate `next` value
2. The `archive-summary.md` remains as a record

No skill currently automates un-archival. This is intentional — restoring a feature should be a deliberate manual action.

## Tips

- Use `/fluent-feature-status --filter VERIFIED` to find features ready to archive
- `--reason completed` is the happy path — feature shipped successfully
- `--reason superseded` is useful when a v2 feature replaces a v1
- `--cleanup` saves disk space but is optional — reports are ephemeral anyway
- The archive-summary.md is a companion file — it won't interfere with other skills
- Bulk archival: run this skill multiple times, once per feature slug
- Archival is reversible — edit status.json to restore if needed

## Post-Execution: Feedback Capture

After completing this skill (whether success or failure), write a feedback record:

1. **Classify outcome:** `SUCCESS` (completed cleanly), `PARTIAL_SUCCESS` (completed after fixing issues), `FAILURE` (could not complete), `BLOCKED` (prereq missing), `USER_CORRECTED` (user overrode approach)
2. **Build record:** Create a `feedback-record-v1` JSON object with:
   - `skill`: `"fluent-archive"`
   - `feature`: feature slug if applicable, null otherwise
   - `phases`: trace of each phase with PASS/FAIL/SKIP
   - `learnings`: any gotchas discovered during execution
   - `userCorrections`: any corrections the user provided
3. **Redact secrets:** Strip tokens, passwords, API keys. Keep business identifiers.
4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-archive.jsonl`
5. **Update** `accounts/<PROFILE>/feedback/index.json` counters (create with `mkdir -p` if missing)

**Skip capture if:** The execution was trivially simple (e.g., user asked a question, no actual write operation happened).

## Known Pitfalls
<!-- feedback-promoted: managed section, updated by feedback loop -->

_(No promoted learnings yet.)_

<!-- end feedback-promoted -->
