importing-design-docs
/importing-design-docs
Przenosi istniejące dokumenty projektowe, RFC, specyfikacje i ADR z repozytorium lub eksportów do Archdocs.
- Autor
- archdocsio ↗
- Repozytorium
- archdocs-plugin ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 04.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 04.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Przenosi istniejące dokumenty projektowe, RFC, specyfikacje i ADR z repozytorium lub eksportów do Archdocs.
Wyzwalacze z opisu
Oryginalny opis (EN)
Use when a team wants to bring existing design docs, RFCs, specs, decision records or ADRs into Archdocs from a repository folder, a GitHub repo, a Notion or Confluence export, or loose markdown files, when the user says import, migrate, port, backfill or "move our docs into Archdocs", or when a repository holds a docs folder of finished design documents that Archdocs doesn't know about yet.
Jak działa
- 1. Find what there is
- 2. Pair, date and identify
- 3. Show the mapping table, then stop
- 4. Import
- 5. After the import
- 6. Check a sample
- 7. Report
- What not to do
Podgląd SKILL.md
--- name: importing-design-docs description: Use when a team wants to bring existing design docs, RFCs, specs, decision records or ADRs into Archdocs from a repository folder, a GitHub repo, a Notion or Confluence export, or loose markdown files, when the user says import, migrate, port, backfill or "move our docs into Archdocs", or when a repository holds a docs folder of finished design documents that Archdocs doesn't know about yet. --- # Importing existing design docs A team that adopts Archdocs already has history: RFCs in a repository folder, design pages in Notion, decision records in `docs/adr`. Imported documents are history, not new work. They land in their final status with the original date, author, identifier and a link back to where they came from, and they skip review, approvals and notifications. The point of importing is that search, `get_task_context`, an object's "Used in" and supersession chains work on day one, before the team writes anything new. The tool is `import_design_doc`, one call per document. Decision records go through `create_adr` with `historical: true`. Both need a Team plan or higher. When the server refuses with a plan error, tell the user and stop; there is no workaround. You do the judgment the server cannot: deciding what each file is, pairing specs with plans, reading status and dates out of git or export metadata, and showing the person a table before anything lands. Nothing is imported until they approve that table. ## 1. Find what there is Ask for the source if the user hasn't named one: a folder in the current repository, another repository, a Notion or Confluence export (a zip of markdown plus CSV), or a set of files. Read the whole set before classifying anything, because conventions only show across files. Classify each file as one of: - **spec**: why and what. Headings like Problem, Goals, Decision, Alternatives, Risks, Design. - **plan**: how. Ordered tasks, phases, checklists, rollout steps. - **RFC or design page**: design and rollout in one document. - **decision record**: MADR shape (Context, Decision, Consequences, Options) or an `adr/NNNN-*.md` path. - **implementation report or evidence**: a write-up of what actually shipped, often `*-report.md` next to a plan. It becomes the `evidence` variation of the document it reports on. - **work log**: a running log of the work, with one dated entry after another (`worklog.md`, `## 2026-03-04` headings, a progress section that grows by date). It becomes the journal of the document it logs. A single resume or handoff note is not a work log. - **not a document**: README, index, template, meeting notes, changelog, outlines, manual QA checklists, resume or handoff notes, review suggestions. List these for the user; don't import them. Use the signals the files give you: frontmatter, the first heading, filename patterns (`2026-03-04-billing-design.md` and `2026-03-04-billing.md`, `RFC-042-*.md`, `0007-use-postgres.md`), Notion CSV properties. When you cannot classify a file, put it in the table as unclassified with your best guess marked, and let the person decide. ## 2. Pair, date and identify Pair a spec with its plan when they share a topic slug and were written close together. A pair becomes one design doc with two variations. Classify by the file's name and content, not by the folder it sits in: a plans folder often holds reports, outlines and checklists, and a specs folder may hold `*-plan.md` files. A plan written in phases (`...-phase-1-...`, `...-phase-2-...`, `...-00-contracts.md`) is one plan variation: join the files in filename order, each under a comment naming its file. A report that matches the slug becomes the evidence variation, and a work log that matches it becomes that document's journal. An RFC that mixes design and rollout stays one document and lands whole in the spec variation unless the person asks to split it; when they do, say in the table which headings go to the plan. For each document, find: - **Status.** Frontmatter `status`, a Notion Status column, or a "superseded by" or "replaced by" line. Otherwise read git: a plan whose tasks landed on the default branch is shipped; a document nobody touched since, with its code in the tree, is shipped. When nothing says otherwise, propose SHIPPED and mark it as a guess. Use ABANDONED only when the text or history says the work stopped. Use DRAFT only for documents people are still writing; a draft lands editable and open, not as history. - **Original date.** Frontmatter date, Notion Created, else the date of the commit that added the file (`git log --diff-filter=A --format=%aI -- <file>`). - **Original author.** Frontmatter author, Notion Owner, else the author of that first commit. Pass the name as `originalAuthor` and, when you have it, the email as `originalAuthorEmail`; the server matches it to a member of the organization. - **External id.** The team's own identifier: `RFC-042`, `ADR-0007`, a Notion page id. When the documents have no numbering, use the file path relative to the repository root. It must be stable, because a second run with the same id updates the document instead of duplicating it. - **Source url.** The GitHub blob URL on the default branch, the Notion page url, or nothing when the files came from a local folder with no remote. - **Supersedes.** When a document says it was replaced, record which document replaces it, by external id. Never invent a date, author or status. A column you cannot fill stays empty, and the server records the import date instead. ## 3. Show the mapping table, then stop Present one table, one row per document to import: | file(s) | title | variations | status | date | author | external id | superseded by | notes | For a work log, write `journal (N entries)` in the variations column, and in the notes say which entries carry only a day and no time. Mark every guess in the notes column. Below the table list the files you skipped and why. Ask the person to approve, edit or drop rows. Do not call `import_design_doc` before they answer. For more than about fifty documents, offer a first batch of ten so they can check the result in the app before the rest goes in. ## 4. Import Call `import_design_doc` once per approved row: - `sourceSystem`: `github` for a repository, `notion`, `confluence`, `markdown` for loose files, `other`. - `externalId`, `sourceUrl`, `originalAuthor`, `originalAuthorEmail`, `originalDate` from the table. - `status` and, for ABANDONED, `abandonedReason` from the text; for SUPERSEDED, `supersededBy` with the replacing document's `externalId`. - `variations`: the markdown of each variation by type key (`spec`, `plan`, `evidence`, or the organization's own keys from `list_design_doc_types`). Send the file body as it is; the server drops a leading frontmatter block, removes NUL characters and stores canonical markdown. Do not rewrite, trim or "improve" the text. - `changeType` only when a document clearly is one of the organization's other change types by their `whenToUse` (a bug-fix writeup with no spec). Leave it out otherwise; historical imports default to Standard change. - A `brief` per variation when you can write one honestly from the text (what was decided, the risks it names, the alternatives it rejected). The brief must say what the document says. When you can't, leave it out and the server stores a placeholder naming the source. - `autoLink: true`, so plain-text names of catalog objects become mentions. Order matters only for supersession: `supersededBy` needs the replacing document to exist already. Import the documents that replace others first, or import everything and re-import the superseded rows afterwards; re-import is idempotent. Decision records go through `create_adr` with `historical: true`: `status` (`ACCEPTED`, `REJECTED` or `DEPRECATED`; leave it out for a proposal), `decisionDate`, `context`, `decisionOutcome` and `consequences` from the MADR sections, `consideredOptions` when the record lists them, and the same provenance fields. A superseded decision is imported first, then its replacement, then `supersede_adr` links them. Each result carries the document's `url`. Keep them for the report. ### Work logs `import_design_doc` takes document variations only, so a work log goes in after its document has landed, one `add_journal_entry` call per entry: - `designDocId` from the import result, and `variation` set to the key of the organization's journal type (the type with `contentMode: "JOURNAL"` in `list_design_doc_types`, usually `work-log`). - `kind` from that journal type's entry kinds: `progress` unless the entry plainly records a decision or a change from the plan. - `summary` is the entry's first line or heading, cut to 300 characters. `body` is the rest of the entry as written. - `occurredAt` is the entry's own date and time, in ISO 8601 with an offset. When the log gives a day and no time, use noon UTC that day (`2026-03-04T12:00:00Z`) so the entry stays on its day in every time zone, and say so in the notes column. When an entry has no date at all, ask the person. Never leave `occurredAt` out of an imported entry, because then the entry is dated today. Replay oldest first. Archdocs numbers entries in the order you add them, so a log replayed newest first reads backwards. Entries are recorded under your token. When the log names who wrote an entry, that name stays in the text. Journal entries are not idempotent, so a second run adds every entry again. Before replaying into a journal that already has entries, read it with `list_journal_entries` and add only what's missing. ## 5. After the import - Each result lists `unresolved` names that didn't match a catalog object. Fix them with `link_design_doc_mentions` when the right object exists, or report them. - When a document has a decisions section that reads like a standing rule, offer to record it as an ADR with `create_adr`. Don't create ADRs unasked. - When a document has a lessons or postmortem section, offer to capture it with `propose_knowledge_item` so later changes on the same code see it. A person accepts the capture; it is never an approved rule. - When a status or title turned out wrong, re-run `import_design_doc` with the same `externalId` or `sourceUrl`; the document is updated in place and gets a new version. ## 6. Check a sample After the first batch, open two or three results in the app (their `url`) and confirm the title, status, date and alias read right, that a paired document shows both tabs, and that search finds a document by its original identifier. Fix anything wrong with a re-import before continuing. ## 7. Report Tell the person what landed: how many documents, with each one's `url`; how many journal entries went into each work log; the rows they dropped; the unresolved names; and anything the server refused, with the reason. Imported documents already carry their status, so there is nothing to ship or mark ready. Stop there unless they ask for the next batch. ## What not to do - Don't import before the table is approved, and don't import rows the person dropped. - Don't change the documents' words. Encoding and line endings only. - Don't guess silently. A guess goes in the notes column; an empty field stays empty. - Don't use `create_design_doc` plus `write_design_doc_variation` for history. That path creates a draft dated today, authored by the token holder, and an agent cannot ship it. - Don't import a document people are still editing elsewhere as SHIPPED. Ask where it lives now. - Don't replay a work log without `occurredAt`, newest first, or twice.
Wersje
W bazie nie ma innych skilli o nazwie importing-design-docs.
Migawka bazy z 13.11.2026 · wersja paczki a1a3fdabe140 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100using-design-docs
Sprawdza przed zmianą w kodzie, czy potrzebny jest dokument projektowy Archdocs, zapis decyzji architektonicznej lub aktualizacja diagramu. - 100writing-a-design-doc
Tworzy i edytuje dokumenty projektowe Archdocs z diagramami, specyfikacją, planem wdrożenia i otwartymi pytaniami. - 90confluence-to-markdown
Przenosi przestrzeń Confluence do plików Markdown w drzewie folderów z działającymi linkami, używając darmowego konwertera. - 95confluence
Odczytuje strony i komentarze Confluence, aby pobrać dokumenty projektowe, ADR, runbooki i inne treści wiki jako kontekst do zadań. - 100rfc-writer
Pisze dokumenty projektowe dla inżynierów: RFC, ADR, specyfikacje techniczne i design docy z kontekstem, problemem, propozycją, alternatywami, konsekwencjami i słowami kluczowymi RFC 2119. - 100design-docs
Pisze i przegląda dokumenty projektowe RFC oraz ADR z celami, alternatywami, ryzykiem, bezpieczeństwem, wdrożeniem i obserwowalnością.