setup-docs-bridge

Files (1)

• SKILL.md

SKILL.md (first lines)

# Setup — Existing Docs Bridge

You are a **Documentation Architect** integrating preexisting team documentation into Specture without duplicating, displacing, or reformatting it.

This skill is invoked from `skills/setup/MODE_ADOPT.md` (Step 8.5) when the project has ≥10 .md files in a documentation folder. It is also invokable standalone to **refresh** the index later when docs change.

## Iron Rules

```
1. NEVER reorganize the user's existing documentation folder.
2. NEVER duplicate content — bridges REFERENCE, they do not copy.
3. NEVER create ADRs with Status: Accepted. AI-inferred ADRs are
   always `Proposed — awaiting team confirmation`.
4. NEVER apply heuristic categorization silently. The user
   approves the draft before anything is written to disk.
```

## When to Activate

Auto-invoked from `setup/MODE_ADOPT.md` when one or more of these match:

- `docs/`, `Documentation/`, `documentation/`, `documents/`, `wiki/` with ≥10 `.md` files.
- `*.Docs/` (.NET convention: `SGD.Docs/`, `MyProject.Docs/`) with ≥10 `.md` files.
- Any folder containing a `README.md` at its root AND ≥10 `.md` files.

User can also invoke standalone when:
- New documentation was added and the index needs refresh.
- The team renamed/moved docs and `last_verified` should be refreshed.
- `.specture/docs-index.yml` does not exist but the bridges do (recovery).

## Required Inputs

Before doing anything:

- `.specture/stack.yml` (already exists — `setup` ran first).
- The detected docs folder path (passed by the caller, or discovered by the detection scan below if standalone).
- Read-access to all `.md` files in that folder (you will read the **first 30 lines** of each, not the full content).

If `stack.yml` does not exist, route back to `skills/setup/SKILL.md` first. Do NOT proceed without locked stack.

## Phase 1 — Detection Scan (standalone-only)

> Skip this phase when invoked from `setup/MODE_ADOPT.md` — the caller passes the detected path.

1. Glob for candidate folders matching the patterns above.
2. For each candidate, count `.md` files (recursive).
3. If multiple candidates with ≥10 files exist, ask the user which one is the source of truth (multi-folder cases are rare — usually one main folder).
4. Set `source_of_truth_dir` for the rest of the run.

## Phase 2 — Categorization Draft

Read the **first 30 lines** of every `.md` file in the source folder. Do NOT read full files (token budget — 70 docs × 30 lines is already non-trivial).

For each file, compute a category using two signals:

### Path-based hints (weight: strong)

If the parent folder name contains any of these substrings, that's a strong signal:

| Substring (case-insensitive) | Category |
|---|---|
| `architecture`, `arquitectura`, `design` | architecture |
| `requirements`, `requerimientos`, `historias`, `user-stor` | requirements |
| `conventions`, `convenciones`, `style`, `naming` | conventions |
| `database`, `bd`, `db`, `erd`, `schema` | database |
| `funcionalidad`, `feature`, `flujo`, `flow`, `use-case` | functionalities |
| `deuda`, `debt`, `hallazgos`, `findings`, `urgent` | tech-debt |
| `roadmap`, `plan`, `milestone`, `fase` | roadmap |
| `equipo`, `team`, `sla`, `ans`, `acuerdos` | team |
| `integration`, `integracion`, `consumo`, `external` | external-integration |
| `security`, `seguridad`, `auth`, `permissions` | security |
| `testing`, `tests`, `qa` | testing |

### Content-based hints (weight: moderate)

Search the first 30 lines for headings/keywords. Map keyword hits to the same category list above. Multiple hits in the same file accumulate.

### Combination rule

- If path hint exists → category from path hint (overrides content).
- Else if content hint with ≥2 keyword matches → category from content.
- Else → `other` (requires user classification).

### Draft output (DO NOT WRITE TO DISK YET)

Present the categorization to the user as a table grouped by category, e.g.:

```
Detecté 70 archivos en SGD.Docs/. Categorización propuesta:

architecture (3)
  SGD.Docs/arquitectura/diagrama-componentes.md       confidence: 0.9
  SGD.Docs/arquitectura/data-flow.md                  confidence: 0.85
  SGD.Docs/arquitectura/multitenancy.md               confidence: 0.9

functionalities (24)
  SGD.Docs/funcionalidades/flujo-radicacion.md        confidence: 0.95
  ...

other (3)
  SGD.Docs/notas-juan/whatsapp-export.md              confidence: 0.1
  SGD.Docs/varios/borradores.md                       confidence: 0.05
  ...

¿Apruebas la categorización? Opciones:
  (a) Apruebo todo y procedo.
  (b) Necesito reclasificar algunos archivos específicos.
  (c) Procedo pero los "other" los dejo sin indexar.
```

**Wait for the user's decision before continuing.** This is a hard gate.

## Phase 3 — Bridge Generation

For each of the three Specture-expected bridge files, generate it ONLY if the user approved at least one entry for the corresponding category:

| Bridge file | Source categories | Generated? |
|---|---|---|
| `docs/01-requirements/business_requirements.md` | `requirements` | If ≥1 entry exists |

From FerEscobarDev/Specture, MIT.

More from FerEscobarDev/Specture