# Generate Architecture Docs

> Generate and continuously update architecture documentation and architecture-image prompts from mixed source artifacts. Use when inputs change often and you need incremental updates, careful evidence processing, and timeline maintenance in a separate output folder.

- Skill: `arn-nj/generate-architecture-docs` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add arn-nj/generate-architecture-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arn-nj/generate-architecture-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: arn-nj (https://skillmd.com/u/arn-nj)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/arn-nj/generate-architecture-docs

---


# Architecture Docs From Mixed Sources

## What This Skill Produces
- Normalized evidence inventory from heterogeneous sources (`.doc`, `.docx`, `.pdf`, `.txt`, `.md`, `.msg`).
- Consolidated architecture facts and assumptions with traceability.
- Architecture documents generated from project templates.
- Architecture options analysis with pros and cons when no established architecture is available.
- Additional architecture outputs aligned with architecture playbooks.
- Architecture image prompt packs aligned with architecture image prompt playbooks.
- Auto-created template folders/files when missing.
- Incremental updates that preserve prior outputs and update only changed areas.
- A maintained architecture timeline of decisions, source changes, and document revisions.

## Use When
- You need to transform fragmented project knowledge into formal architecture documentation.
- Inputs span wiki exports, meeting notes/transcripts, mails, and ad-hoc docs.
- You want a repeatable process portable across repositories.
- You prefer to provide only one source root and let the skill auto-discover everything else.
- Inputs keep changing over time and documents must stay current without losing history.

## Required Input
- Exactly one path: `inputSourceFolder`.
- This folder can be either:
1. A combined source root that already contains mixed artifacts.
2. A workspace root from which the skill auto-discovers subfolders (for example: `wikis`, `meetings`, `mails`, `additional-context-docs`, `docs`).
3. An empty folder for first-time setup; in this case the skill must create the expected source and output structure automatically.

## Detail-First Generation Mechanism (Default)
Use `detailed-sequential` generation by default.

Process rules:
1. Generate one major document at a time, complete it, run a file-level quality gate, then continue.
2. Avoid broad shallow generation across all outputs at once.
3. Process files in this order:
1. primary architecture design document from template set
2. workflow/business logic document
3. data model document
4. playbook-applied architecture document
5. architecture options document (conditional)
6. diagrams and image prompts
4. Only after core documents pass depth checks, finalize traceability and timeline updates.

Minimum depth gate per narrative document:
1. Section content must be concrete and implementation-relevant.
2. Each major claim must include at least one evidence/source reference.
3. Include assumptions, risks, and unresolved questions explicitly.
4. Prefer tables/examples where they improve clarity.
5. Replace generic placeholders with focused `TBD` questions when evidence is missing.

Document-family depth gates:
1. Architecture design document(s)
- Must be fully written, not outline-only.
- Must include business context, scope, component boundaries, data/integration, deployment, NFRs, risks, and decisions.
- Must include section-level source references.
2. Image prompts
- Must include a detailed prompt per required diagram family.
- Must specify scope, style, labels, composition, and architecture reference.
3. Open questions
- Must be specific, grouped by topic, and tied to source gaps or decisions.
- Each question must explain why it blocks or constrains the architecture.
4. Architecture options document (conditional)
- Must include at least three options, detailed pros/cons, and a recommendation.

## Packaged Defaults
Resolve defaults from the skill package itself:
1. Template assets:
- Primary: [workspace template bundle](./assets/templates/from-workspace/)
- Fallback: [starter templates](./assets/templates/architecture/)
2. Architecture and image playbooks:
- [packaged playbooks](./assets/playbooks/)
3. Output root (separate folder): `generated-architecture-output/`

Reference: [packaged defaults](./assets/workspace-defaults.md)

## Output Contract
Create or update these outputs under `generated-architecture-output/` (or an equivalent dedicated output root if already configured):
1. `evidence/evidence-index.md`
2. `evidence/source-facts.md`
3. `architecture/` documents generated from templates
4. `image-prompts/` prompt files aligned to image playbook format
5. `traceability/requirements-to-evidence-map.md`
6. `traceability/open-questions.md`
7. `timeline/architecture-timeline.md`
8. `timeline/source-change-log.md`
9. `timeline/document-revision-log.md`
10. `.state/last-run-source-snapshot.json`
11. `.state/last-run-doc-checksums.json`

Conditional output (required when architecture baseline is not established in sources):
1. `architecture/Architecture_Options_Pros_Cons.md`

Structure compatibility rule:
- Keep old output-structure files when they already exist.
- When generating updated outputs, also update equivalent old-structure files so downstream consumers keep working.
- If an old-structure file has no equivalent in the current run, leave it unchanged and mark it as `legacy-unmapped` in the revision log.

When output folders do not exist, create them before processing.

## Procedure
1. Discover and validate paths from one input.
- Confirm `inputSourceFolder` exists.
- Auto-discover source folders from `inputSourceFolder` and common children (`wikis`, `meetings`, `mails`, `additional-context-docs`, `docs`).
- Resolve template/playbook paths from packaged defaults.
- If primary packaged assets are missing, use fallback packaged templates and continue.

2. Bootstrap empty input folder when needed.
- If `inputSourceFolder` has no supported files and no expected source subfolders, create:
1. `wikis/`
2. `meetings/`
3. `mails/`
4. `additional-context-docs/`
5. `docs/`
- Add placeholder notes (`README.md`) in each created source subfolder describing what to place there.
- Create output scaffold immediately:
1. `generated-architecture-output/evidence/`
2. `generated-architecture-output/architecture/`
3. `generated-architecture-output/image-prompts/`
4. `generated-architecture-output/traceability/`
5. `generated-architecture-output/timeline/`
6. `generated-architecture-output/.state/`
- Record this as `Initial scaffold created` in `traceability/open-questions.md`.

3. Bootstrap template assets when missing.
- Ensure output template workspace exists under generated outputs.
- Ensure required template files exist; if missing, copy from [workspace template bundle](./assets/templates/from-workspace/) or fallback [default templates](./assets/templates/architecture/).
- Record bootstrapped files in `traceability/open-questions.md` as `Auto-created asset` notes.

4. Initialize update mode and state.
- If `.state/last-run-source-snapshot.json` exists, run in incremental mode.
- If state is missing, run in baseline mode and create initial state.
- Never delete prior timeline files; only append new entries with timestamps.
- Use `.state/last-run-doc-checksums.json` to detect changed source documents and changed generated docs.
- Regenerate only impacted artifacts while preserving stable docs.

5. Build evidence inventory.
- Recursively enumerate supported files in source folders.
- Record per-file metadata: path, type, last modified date, and inferred topic.
- De-duplicate near-identical files by filename/date/content hash when available.

6. Detect source deltas.
- Compare current inventory with prior snapshot and classify each file as `added`, `updated`, `removed`, or `unchanged`.
- Prioritize extraction and downstream regeneration based on changed files first.
- Record delta summary in `timeline/source-change-log.md`.
- Treat document deltas (`.md`, `.docx`, `.pdf`, `.txt`, `.msg`) as first-class triggers for architecture updates.

7. Extract text from sources.
- For `.txt`, `.md`: parse directly.
- For `.pdf`: extract text with available tooling.
- For `.doc`/`.docx`: extract text with available tooling.
- For `.msg`: capture sender/subject/date/body and relevant attachments when accessible.
- If extraction fails for a file, log it in `traceability/open-questions.md` and continue.

8. Normalize and classify facts.
- Convert extracted text into structured fact cards:
1. Functional behavior
2. Non-functional requirements
3. Integrations and external dependencies
4. Data entities and flows
5. Security/compliance constraints
6. Deployment/runtime constraints
- Tag each fact with source references.
- Separate explicit facts from inferred assumptions.

9. Resolve conflicts and ambiguity.
- Detect contradictory facts (for example, two different API contracts).
- Apply precedence rules:
1. Approved architecture docs
2. Official API specs
3. Recent meeting decisions
4. Email discussions
5. Older notes
- Keep conflicts and unresolved items in `traceability/open-questions.md`.

10. Generate architecture options when baseline is missing.
- If sources do not define a clear existing architecture baseline, create `architecture/Architecture_Options_Pros_Cons.md`.
- Include at least three viable options.
- For each option, document:
1. Option summary
2. Pros
3. Cons
4. Risks
5. Operational impact
6. Migration complexity
- Add a recommended option with decision rationale and assumptions.

11. Generate architecture docs from templates.
- For each template, generate a filled document using normalized facts.
- Preserve template section structure and headings.
- Leave no section blank; if unknown, write `TBD` plus blocking question.
- Add a `Sources` block per section listing evidence references.
- In incremental mode, update only impacted sections when possible and preserve stable sections.
- Keep chronology out of architecture documents; store all run/change history only under `timeline/`.

12. Generate playbook-aligned architecture artifacts.
- Apply architecture playbook instructions to produce required companion docs.
- Ensure terminology consistency across all generated docs.
- Validate document set covers context, components, interactions, data, deployment, risks, and decisions.

13. Generate architecture image prompt packs.
- Apply architecture image prompt playbook formatting.
- Produce prompt variants per major diagram type (for example: context, component, deployment, data flow).
- Include explicit style, labeling, and scope constraints in each prompt.

14. Maintain timeline artifacts.
- Append one entry per run in `timeline/architecture-timeline.md` with date/time, key decisions, risks, and major doc changes.
- Append document-level changes to `timeline/document-revision-log.md` with file path, section, change type, and evidence references.
- Ensure removed/obsolete source files are represented as timeline events, not silently discarded.

15. Run quality checks.
- Completeness check: all template sections addressed.
- Traceability check: each major claim maps to at least one source.
- Consistency check: component names and interfaces are uniform across files.
- Ambiguity check: unresolved items documented with owner/question.
- Timeline integrity check: every significant document change has a corresponding timeline/revision entry.
- Sequencing check: each major file passed file-level gate before next file generation.
- Depth check: documents are review-ready and not outline-only.

16. Publish outputs and summary.
- Write generated files to the dedicated output root.
- Produce a run summary with:
1. Sources processed
2. Source deltas (`added`, `updated`, `removed`, `unchanged` counts)
2. Extraction failures
3. Conflicts found
4. Documents generated
5. Open questions
6. Timeline entries added
- Include preserved existing docs count and updated docs count.
- Include per-file generation order and gate outcome summary.
- Persist current source and document snapshots under `.state/` for the next incremental run.

## Decision Points
- If sources are sparse or low quality: produce a minimal architecture baseline and expand open questions.
- If no established architecture is found: generate `architecture/Architecture_Options_Pros_Cons.md` and carry recommendation rationale into architecture docs.
- If templates and playbooks conflict: prioritize templates for structure, playbooks for style/content depth, and record deviations.
- If multiple versions of the same spec exist: prefer latest approved version and cite discarded versions in traceability notes.
- If packaged playbooks are missing: use nearest equivalent packaged file and record selection rationale.
- If source signals conflict across time: prefer newer timestamped evidence unless superseded by formally approved artifacts.
- If a source is removed: do not erase prior decisions; mark status as `possibly obsolete` and add a review question.

## Completion Criteria
- All required output artifacts are present.
- If no established architecture exists in sources, `architecture/Architecture_Options_Pros_Cons.md` is present with at least three options and a recommendation.
- Every generated architecture section has either grounded content or explicit `TBD` with a question.
- Open issues are consolidated in one place with source links.
- Architecture image prompts exist for all mandatory diagram families.
- A reviewer can trace major architectural decisions back to evidence.
- A dedicated output folder is used; source folders remain untouched.
- Old structure files remain available and are synchronized where equivalent outputs exist.
- Timeline files are updated for the run and remain chronologically consistent.
- A reviewer can understand what changed since the previous run without diffing raw files.

## Invocation Pattern
When invoked, ask only for:
1. `inputSourceFolder`

Then:
1. Auto-resolve templates/playbooks from packaged defaults.
2. Auto-create missing template folders/files from packaged assets.
3. Auto-create a dedicated output folder.
4. Execute the workflow and report output paths plus unresolved questions.

Optional metadata (system name/domain/environment) may be inferred from source content if not provided.