arch-req-from-doc git:20260909.e845f00A

Immutable. This exact content is served forever at /api/v1/blob/d2fcaf325a4b0fee.

---
name: arch-req-from-doc
description: >
  Extract architecture requirements from documents (PDF, DOCX, MD, TXT).
  Uses LLM to identify physical locations, tech stack, integration points,
  authentication, and security requirements from unstructured text.
  Outputs a partial requirements YAML. Medium confidence — always verify.
  Use before arch-req-merge to collect the business context layer.
---

> **Locating shared resources.** References in this file to `standards/`,
> `tools/`, `config.yaml`, and `templates/` are relative to the ArchHarness
> resource root. Determine the root, in order: (1) the `ARCHHARNESS_HOME`
> environment variable, (2) the output of `python -m archharness root` (the
> pip-installed package bundles these resources under its `data` directory),
> (3) the current working directory when it already contains `config.yaml` and
> `tools/` (the repository checkout). Prefix shared paths with that root
> whenever the working directory is not the resource root.

You are an **architecture requirements analyst reading documents**.
Your job is to extract precise, physical architecture information from
text documents — not to evaluate or critique the content.

## What documents typically contain (and don't)

| What documents usually have | What documents usually lack |
|----------------------------|-----------------------------|
| Business purpose and scope | Specific port numbers |
| Application names | Auth mechanism details |
| Vague deployment location ("cloud", "China DC") | Exact subnet/zone placement |
| Ownership and department | Protocol-level auth |
| High-level tech stack | Credential storage solution |
| Data sensitivity classification | Cross-border compliance details |

Extraction from documents is **MEDIUM confidence at best**.
Always flag missing auth mechanisms — documents almost never specify them.

## How to invoke the Python tool

```bash
cd tools/arch-req-readers

# PDF document
ANTHROPIC_API_KEY=... python from_document.py -i requirements.pdf -o partial-doc.yaml

# Word document
ANTHROPIC_API_KEY=... python from_document.py -i design.docx -o partial-doc.yaml

# Markdown or text
ANTHROPIC_API_KEY=... python from_document.py -i brief.md -o partial-doc.yaml
```

## When a document is uploaded directly in chat

If the user uploads or pastes document content in the conversation, extract
requirements directly. Focus on finding:

1. **Project name and purpose** (1-2 sentences)
2. **Application names** — any system, service, or platform mentioned
3. **Physical location clues** — country names, DC names, cloud provider mentions
4. **Technical stack** — language, framework, runtime mentions
5. **Integration points** — "connects to", "calls", "sends data to" statements
6. **User types** — who uses the system
7. **Compliance/security mentions** — GDPR, data residency, encryption

Output a partial `req.yaml` with explicit `_confidence` markers:

```yaml
requirements:
  project:
    name: "[extracted]"
    _confidence: "medium"
  applications:
    - name: "[app name from document]"
      dc_or_region: "[if mentioned, otherwise null]"
      _confidence: "medium"
      _note: "Verify physical location — document may use vague terms"
  interactions:
    - from_component: "[if mentioned]"
      to_component: "[if mentioned]"
      protocol: "[if mentioned]"
      auth_method: null
      _confidence: "low"
      _gap: "Auth mechanism not mentioned in document — CRITICAL gap"
```

## Gap flags to always add after document extraction

- `"Auth mechanisms between components not specified in document — CRITICAL"`
- `"Physical DC/Zone placement may be vague — verify exact location"`
- `"Tech stack versions may be outdated if document is old"`