AI Artifact Provenance: Documents That Explain Themselves

Summary

I wrote orders-db-memo.md: a one-page decision memo that recommends Postgres (Aurora) over DynamoDB, 430 words. At the end is an ai-artifact-provenance block, so your VP, or their assistant, can see what you asked, what I assumed, and what I didn't verify, without having been in this session.

The memo (excerpt)

Recommendation: Aurora PostgreSQL for the orders service.
Orders need multi-row transactions (order + line items + inventory hold) and ad-hoc reporting queries. DynamoDB would mean designing single-table access patterns up front and building reporting through exports.

The provenance block (end of the file)

{
  "ai_artifact_provenance": "0.1",
  "title": "Orders service: Postgres vs DynamoDB",
  "ask": "Write a one-page decision memo comparing Postgres and DynamoDB for our orders service. Keep it under 500 words, it's for my VP. We're staying on AWS.",
  "purpose": "Pick the primary datastore for the orders service",
  "audience": "VP Engineering",
  "status": "proposal",
  "owner": "<you>",
  "generator": { "tool": "Claude Code", "model": "claude-opus-5-5" },
  "created": "2026-10-16",
  "updated": "2026-10-16",
  "inputs": [ { "name": "services/orders/schema.sql", "as_of": "2026-10-16" } ],
  "constraints": [
    { "quote": "Keep it under 500 words", "source": "user" },
    { "quote": "it's for my VP", "source": "user" },
    { "quote": "We're staying on AWS.", "source": "user" }
  ],
  "assumptions": [
    { "text": "Peak load stays under 2,000 orders/minute for the next 18 months", "confirmed": false },
    { "text": "The team has more SQL than DynamoDB experience", "confirmed": false }
  ],
  "decisions": [
    {
      "id": "D1",
      "decision": "Recommend Aurora PostgreSQL",
      "why": "Multi-row transactions and ad-hoc reporting are core to orders",
      "quote": "We're staying on AWS.",
      "rejected": [
        { "option": "DynamoDB", "why": "Access patterns must be fixed up front; reporting needs an export pipeline" },
        { "option": "Self-managed Postgres on EC2", "why": "Ops burden with no benefit at this scale" }
      ],
      "superseded_by": null
    }
  ],
  "unknowns": [
    { "text": "Aurora cost at projected volume", "how_to_check": "AWS pricing calculator with last quarter's order counts" }
  ],
  "changelog": [
    { "version": 1, "date": "2026-10-16", "trigger": "Write a one-page decision memo comparing Postgres and DynamoDB...", "changed": "First draft." }
  ],
  "how_to_question": "Give this file to your own assistant and ask it to read the ai-artifact-provenance block."
}

Next steps

• Confirm or correct the two assumptions; I'll flip confirmed and add a changelog entry.
• Ask for revisions as usual. Each republish appends to the changelog and never rewrites it.
• Want the context visible on the page? Ask for the provenance panel (HTML) and a collapsed "How this document was made" bar appears at the top.