Uw Complete

Completing Layer Documentation

Purpose: Process gaps.md files and add all missing documentation to layer files.

Input: docs/unwind/layers/{layer}/gaps.md from verification step Output: Updated section files with gaps filled

> Anchor ids matter. gaps.md (when generated by the deterministic > verifier) lists an Id for each missing item. Document it with the anchor-id > heading format so re-verification matches and the coverage loop converges: > > ``markdown > ### [MUST|SHOULD|DON'T] > ` > > If an item should NOT be in the rebuild, move it to an ## Excluded` section > with a one-line reason instead of documenting it (see analysis-principles.md 16).

Process

Step 1: Read gaps.md

For each layer, read docs/unwind/layers/{layer}/gaps.md to get:

• Missing items (with source location and target section)
• Inaccuracies (with what needs fixing)
• Uncategorized items (needing tags)

Step 2: Dispatch Completion Agents

For each layer with gaps, dispatch an agent to fix them:

Task(subagent_type="general-purpose")
  description: "Complete [layer] documentation gaps"
  prompt: |
    Read docs/unwind/layers/{layer}/gaps.md for the work list.

    For each MISSING item:
    1. Read the source file at the specified location
    2. Document the item following analysis-principles.md
    3. Add to the specified section file using the anchor-id heading:
       ###  [MUST/SHOULD/DON'T] 
    4. Copy the gaps.md Id verbatim so re-verification matches

    For each INACCURACY:
    1. Read the source file
    2. Fix the documentation to match actual code

    For each UNCATEGORIZED item:
    1. Add appropriate [MUST/SHOULD/DON'T] tag

    Link format: [from architecture.md]

    After completion:
    - Update index.md with correct counts
    - Delete gaps.md (work complete)

Step 3: Verify Completion

After agents complete, check that:

• All gaps.md files are deleted (indicates completion)
• Section files have been updated
• Index.md counts are accurate

Agent Prompt Template

Complete the documentation gaps for the {LAYER} layer.

## Work List

Read: docs/unwind/layers/{layer}/gaps.md

## Source Linking

Use this format: {link_format from architecture.md}

## For Each Missing Item

1. Read source at the specified location
2. Document following the layer's format (see uw-analyze-{layer} skill)
3. Add to the correct section file
4. Include [MUST/SHOULD/DON'T] tag as specified

## For Each Inaccuracy

1. Read source at the specified location
2. Edit the documentation to match actual code

## For Each Uncategorized Item

1. Find the item in the section file
2. Add the appropriate tag based on:
   - MUST: Core functionality, business logic, external contracts
   - SHOULD: Valuable patterns, good practices
   - DON'T: Tech-specific implementation details

## When Complete

1. Update index.md with accurate counts
2. Delete gaps.md to signal completion

Parallel Execution

Layers can be completed in parallel - no dependencies between layer completions:

Task(subagent_type="general-purpose", description="Complete database gaps")
Task(subagent_type="general-purpose", description="Complete service-layer gaps")
Task(subagent_type="general-purpose", description="Complete api gaps")
... (all in parallel)

Example Completion Flow

Input gaps.md:

# Database Documentation Gaps

## Missing Items

### audit_logs table
- **Type:** table
- **Location:** src/schema.ts:412-445
- **Category:** SHOULD
- **Section:** schema.md

Agent actions:

1. Read src/schema.ts:412-445
2. Extract table definition
3. Add to schema.md:

### audit_logs [SHOULD]

```sql
CREATE TABLE audit_logs (
  id SERIAL PRIMARY KEY,
  ...
);

| Column | Type | Nullable | Default | Constraints | |--------|------|----------|---------|-------------| | id | SERIAL | NO | auto | PRIMARY KEY | ...

4. Update index.md table count
5. Delete gaps.md

## Handling Large Gap Lists

If a layer has many gaps (20+):
- Process incrementally - write after each item
- Don't buffer all changes
- This prevents token exhaustion

## After Completion — continue or pause?

When all gaps are filled (every `gaps.md` deleted), re-verify to prove the coverage
loop converged before moving on.

**Use AskUserQuestion** to ask whether to continue:
- **Re-verify coverage** *(recommended)* — confirm 100%, then proceed to planning.
- **Pause here** — stop and resume later.

Act in the same turn:
- **Continue** → invoke `unwind:uw-verify` (and, once 100%, `unwind:uw-plan`).
- **Pause** → tell them how to resume: *"Run `unwind:uw-verify` (type `/uw-verify`) to re-check coverage."*

> **Pipeline:** scan → analyze → verify → **complete ✓** → plan → dashboard.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nearform](https://github.com/nearform)
- **Source:** [nearform/unwind](https://github.com/nearform/unwind)
- **License:** MIT

Install and usage instructions live in the source repository linked above.