Architecture Fit Mapper

architecture-fit-mapper produces a solution architecture map in chat. It is the skill most SEs reach for after discovery and fit-gap are stable, when the question becomes “so how does this actually fit together?”. It reuses prior artifacts first, grounds docs claims with Firecrawl when keys exist, and keeps unverified claims as validations instead of guesses.

What this skill is

A conversational architecture-mapping workflow. You hand it a fact sheet or prior fit-gap, product and integration docs, optional local examples, and constraints, and it returns:

• A short summary.
• An architecture map.
• A diagram (rendered as a Mermaid block or ASCII fallback).
• A fit analysis.
• A blockers list.
• Required validations.
• Citations, or clearly labelled assumptions when grounding was not possible.

Under the hood it can call Firecrawl search, scrape, map, and crawl when doc URLs are supplied, and it can push the result to Google Docs or Confluence when you explicitly ask for writeback.

Trigger conditions

Use this skill when the user asks for:

• An architecture map or reference architecture.
• A solution diagram.
• Blockers or risks for implementation fit.
• A validation plan before a POC.
• A high-level design for a pilot.

Intake order

Codex asks one question at a time, in this order:

1. Fact sheet or prior fit-gap context — an artifactRef or a paste.
2. notes.productDocs — URLs for your own product documentation.
3. notes.integrationDocs — URLs for vendor or partner integration docs.
4. notes.constraints — non-negotiables like “must keep HubSpot in the loop”.

notes.examplePaths and notes.targetSystems can be provided up front but are not part of the one-question intake loop. If accountSeed is already in $architecture-fit-mapper ..., the account question is skipped.

Output shape

The artifact is returned in chat with these sections:

1. Summary
2. Architecture map
3. Diagram
4. Fit analysis
5. Blockers
6. Required validations
7. Citations or assumptions

How to best use this skill

Run discovery and fit-gap first. The map is sharpest when it starts from a fact sheet and a fit-gap matrix instead of raw notes. The skill will consume discovery-fact-sheet.json from artifactRefs before falling back to pasted text.

Pass real doc URLs for product and integration docs. The map leans on Firecrawl-grounded docs to describe component surfaces. Product docs go in notes.productDocs; vendor or partner docs go in notes.integrationDocs. Without URLs the affected claims become required validations.

Point at local examples, do not ask Codex to fetch remote repos. v1 supports local code samples and existing artifacts only. Put reusable snippets or diagrams under a local path and reference them in notes.examplePaths. Codex will not clone remote repositories.

State constraints as non-negotiables. Strings in notes.constraints are woven into the fit analysis and the validation plan. Good examples: “Must keep HubSpot and Slack in the loop”, “No outbound egress from the pilot VPC”, “Pilot must stay inside the existing AWS account”.

Expect a Mermaid diagram. The diagram section renders as a Mermaid code block. In the docs site and most Codex surfaces this renders inline. Environments without Mermaid support fall back to ASCII.

Trust validations over smoothed-over claims. Anything not directly evidenced becomes a required validation. That is intentional — the validation list is the backlog the delivery team will pick up.

Save and writeback are opt-in. The map is returned in chat. You can ask for it to be saved as markdown, pushed to a Google Doc, or published as a Confluence page. Each of those is confirmation-gated and needs a connected Composio toolkit.

How to combine with other skills

The architecture map sits between fit-gap and POC handoff in the canonical chain. Every other skill in the middle of the funnel can feed it context.

• From Discovery Context Ingester. A normalized fact sheet is the strongest starting point. Constraints picked up during ingestion flow into the architecture constraints without re-prompting.
• From Integration Fit Gap Analyzer. gap and unknown rows from the fit-gap often become components or required validations in the architecture map. Keep the fit-gap artifact in the same chat so the mapper reuses it.
• Into POC Handoff Orchestrator. The handoff pulls the map’s blockers and validations directly into POC milestones and risks, so you are not re-typing the same list twice.
• Into Security Review Prep. Security prep reuses the architecture component list to build the control matrix. Run the mapper first when the architecture is still in flux.

Example invocations

Explicit:

$architecture-fit-mapper "Acme Health — pilot"

Natural language:

Map the architecture for Acme Health's pilot. Must keep HubSpot and Slack in the loop. Ground against our onboarding integration docs.

Example normalized input (for reference — you never type this directly):

{
  "account": { "name": "Acme Health" },
  "objective": "Map the solution architecture for the pilot",
  "notes": {
    "productDocs": [],
    "integrationDocs": [],
    "examplePaths": [],
    "constraints": [
      "Must keep HubSpot and Slack in the loop"
    ]
  },
  "artifactRefs": [],
  "destinations": {},
  "providerMode": "local-only"
}

Provider behavior

• With FIRECRAWL_API_KEY — Firecrawl is used to ground any supplied doc URLs via search, scrape, map, and crawl. Component claims that resolve against docs carry citations.
• Without FIRECRAWL_API_KEY — the map stays local-only. Claims that would need external evidence are moved into required validations instead of being smoothed over.
• External writeback — requires COMPOSIO_API_KEY and a connected toolkit. Supported toolkits: googlesuper (Google Docs) and confluence. See Connect Google Docs & Sheets and Connect Confluence.

Related reference

• Grounding Rules — why docs URLs beat assumptions and why unverified claims become validations.
• Capability Packs — how the map describes what your product supports without freehanding feature claims.