archive-and-cleanup-vibe-docs

When to Trigger

Use this skill only after:

• A feature or refactor is fully implemented
• The agent is about to open or finalize a PR
• Temporary documents were created during exploration, planning, or iteration

Do not use during active development.

Inputs

The agent may have access to:

• Temporary documents such as:

  • plan*.md
  • progress*.md
  • task*.md
  • design notes, brainstorm files, agent logs

• The final code changes

• Existing project documentation structure

Core Objective

Transform process artifacts into durable engineering assets, while ensuring:

1. PRs remain clean and reviewer-friendly
2. Long-term design decisions are preserved
3. Temporary documents do not accumulate in the repository

Execution Steps (MANDATORY)

Step 1: Inventory & Classification

Scan all temporary documents produced during the task and classify each into one of the following categories:

1. Durable Design Knowledge

   • Architecture decisions
   • Key abstractions and boundaries
   • Important trade-offs (Why X, not Y)

2. PR-Level Context

   • Background needed to understand the change
   • Scope clarification
   • Explicit non-goals

3. Process Noise

   • Daily progress logs
   • Task checklists
   • Iteration history
   • Prompt drafts or agent conversations

Step 2: Knowledge Extraction & Consolidation

2.1 PR Summary (REQUIRED)

Produce a concise, reviewer-oriented summary suitable for a PR description, containing:

• Background (problem being solved)
• Final design decisions (only conclusions)
• Scope and non-scope
• Follow-up items (if any)

⚠️ Do NOT include:

• Chronological progress
• Failed attempts in detail
• Raw task lists

2.2 Architecture / Design Documentation (CONDITIONAL)

If (and only if) durable design knowledge exists:

• Create or update documentation under one of the following:

  • docs/architecture/<feature>/
  • docs/decisions/
  • module-local docs/

Strongly prefer ADR-style documents:

# ADR-XXX: <Decision Title>

## Context
## Decision
## Consequences

Only extract final decisions, not exploration history.

Step 3: Issue & Follow-up Migration

If any temporary documents contain:

• TODOs
• Deferred ideas
• Known limitations

Then:

• Convert them into GitHub Issues or explicit Follow-up notes
• Remove them from temporary documents

Step 4: Cleanup (MANDATORY)

After successful extraction:

1. Delete all temporary vibe coding documents from the repository, including but not limited to:

   • plan files
   • progress logs
   • task trackers
   • brainstorming notes

2. Ensure:

   • No references to deleted files remain
   • No broken links in docs or PR description

⚠️ Temporary documents must not be committed in the final PR.

Output Requirements

At the end of execution, the agent must produce:

1. ✅ A PR-ready summary (text only)
2. ✅ Any new or updated durable documentation
3. ✅ A clean repository state with all temporary documents removed

Strict Rules

• Never commit raw vibe coding documents
• Never include thinking logs or agent conversations
• Prefer clarity and durability over completeness
• If unsure whether something is durable, exclude it

Mental Model

Temporary docs are raw material. The repository only accepts finished products.

Success Criteria

This skill is successful if:

• A reviewer can understand the PR without reading any temporary documents
• The repository contains only long-lived, intentional documentation
• No vibe coding artifacts remain after merge