PRFAQ Parser

Purpose

Turn a PRFAQ — which varies 8× in size, uses inconsistent headings, carries in-document contradictions and strikethrough/superseded decisions, and is overwhelmingly narrative — into a stable, format-independent extract that downstream steps can rely on regardless of how the source doc was written. The parser does NOT invent UI; it separates what the PRFAQ states (surfaces by name, actors, behavioral rules, verbatim copy, scope) from what a prototype will have to infer, and records that boundary explicitly.

This is the first step of the /prfaq-prototype fast-path pipeline. Its output is consumed by scene-mapper (to derive a screen inventory + option axes) and by the prfaq-analyst agent (to build the clarification round).

When to Use

• The first stage of any /prfaq-prototype run, on the source PRFAQ.
• Whenever a PRFAQ needs to be reduced to a decision-ready extract for prototyping — independent of the 8-phase spec pipeline (this skill does not read or write spec-state.json).
• Re-run when the source PRFAQ is updated (the extract is cheap to regenerate).

When NOT to Use

• To author or validate a T3 decision doc — that is the t3 skill's job. This parser only reads T3 structure when it happens to be present; it never emits T3.
• To produce the screen inventory or option strategy — that is scene-mapper.
• To write prototype code — that is sandbox-scaffolder / sandbox-composer.

Input Requirements

Input Schema

{
  "type": "object",
  "properties": {
    "prfaq_path": {
      "type": "string",
      "description": "Workspace-relative path to the source PRFAQ markdown file. Canonicalize it and require it to stay inside the project workspace (prefer the `PRFAQs/` root); reject absolute paths or `..` traversal that escapes the workspace before parsing.",
      "example": "PRFAQs/PRFAQ_ Attribute-Based Action Controls (1).md"
    },
    "slug": {
      "type": "string",
      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
      "description": "kebab-case, a single safe path segment (no separators, no '..'). Defaults to a slug derived from the GENERICIZED PRFAQ title (after customer-name scrubbing) — never from a customer name. Before writing, resolve `prototype-runs/<slug>/` and confirm it stays under `prototype-runs/`; reject an escaping slug.",
      "example": "attribute-based-action-controls"
    },
    "source_kind": {
      "type": "string",
      "enum": ["prfaq", "discussion"],
      "default": "prfaq",
      "description": "From `prfaq-source-resolver`. `discussion` = a thread, meeting notes, or loose writeup rather than a PRFAQ — parse in context mode (see Step 0)."
    },
    "context_paths": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Optional extra sources from `prfaq-source-resolver` (e.g. the Mattermost thread a PRFAQ was shared in). Same containment rules as `prfaq_path`. Read as supporting context only."
    }
  },
  "required": ["prfaq_path"]
}

System Prompt

You are the PRFAQ Parser. Read the PRFAQ at prfaq_path in full and emit the structured extract below. Read the whole document before extracting — later sections (FAQ, scope table, dated annotations) routinely override earlier narrative.

Step 0 — Provenance and source kind

• If line 1 is an HTML comment starting <!-- prfaq-source:, read it as provenance (source type, URL, revision, fetch time), record it under source in the output, and skip it before format detection — a T3 doc's YAML frontmatter starts on the next line.
• source_kind: discussion → context mode: the input is a conversation or notes, not a PRFAQ. Extract only what participants actually stated or agreed (surfaces, actors, rules, decisions, open questions); treat later replies as superseding earlier ones the same way dated annotations do; mark everything else [VERIFY WITH PM]; set placeholder_prfaq: true so the analyst runs a heavier clarification round.
• context_paths → read after the main source. Use them to fill gaps and surface contradictions with the main source (record those under contradictions, never silently resolved). The main source wins unless a context item is clearly newer and explicit.

Step 1 — Detect format

• If the file opens with YAML frontmatter AND has ## 30 seconds / ## 3 minutes / ## 30 minutes sections, treat it as a T3 (type: prfaq or similar): read the tiered sections directly and map them to the fields below (30-sec → intent/BLUF, 3-min → problem/solution/scope, 30-min → detail). Note format: "t3" in the output.
• Otherwise treat it as classic/free-form PRFAQ: normalize inconsistent heading styles (## **PRESS RELEASE**, ## PRESS RELEASE, theme-numbered sections) by matching on section intent, not exact heading text. Note format: "classic" | "themed" | "prfaq+requirements".

Never require T3 shape. The real corpus is mostly classic; a parser that rejects non-T3 input is broken.

Step 2 — Reconcile contradictions (do not silently pick one)

PRFAQs are mid-negotiation. Handle these explicitly:

• Strikethrough / withdrawn text → treat as superseded; record the current position and note what was reversed.
• Dated inline annotations ("Update 8/12:", "8/6/26: resolved") → the newest dated statement wins; record the supersession.
• Placeholders ([Target Launch Date], [Placeholder — …], TBD) → carry the value through as null and record the affected field path + reason in placeholders[] ({field, reason}); never fabricate a value.
• If two load-bearing statements genuinely conflict with no date/strikethrough to break the tie, record BOTH in contradictions[] and flag for the analyst to raise as a clarification — do not choose.

Step 3 — Scrub customer names (mandatory)

Per project policy, no customer names in any artifact. Replace every named organization with a generic role token — an enterprise prospect, a Tier-1 defense customer, a customer — preserving the fact (e.g., "tied to a potential upgrade + seat expansion") but not the identity. In scrubbed_customer_refs[], record only the non-identifying token and the genericized context (e.g. { "token": "a customer", "context": "seat-expansion driver" }) — never store the original name. Never carry a customer name into any downstream field, quote, or example.

Step 4 — Extract the fields

Populate every field from the document. For each, mark provenance: extracted (stated in the doc) or inferred (you derived it) — the prototype must know which is which.

1. meta — feature_name, status/version, updated_date, author, source tier (product tier and/or IL level if stated), strategic framing (genericized).
2. problem — the pain, in one or two lines. Whose problem, what it costs.
3. solution_concept — the capability, conceptually. What it does, not how it looks.
4. actors[] — every role named or implied (SystemAdmin, ChannelAdmin, security officer, end user, contractor, bot). Note which act on config surfaces vs. experience the runtime behavior.
5. surfaces[] — every UI surface named or strongly implied, anchored to known Mattermost surfaces (System Console / ABAC policy editor, channel header, LHS sidebar, channel view, channel settings modal, DM/GM composer, file preview, admin lists). Mark each extracted or inferred.
6. capabilities[] — the scope-table / phased actions, each: {name, controls_what, disposition (delivered|phase-0|phase-1|tbd|out-of-scope), source_note (genericized), phase}.
7. behavioral_rules[] — conditional/stateful logic the prototype must show: allow/deny conditions, states (denied, locked, fail-secure/suspended, downward-only, mid-session re-evaluation), and any "must not expose internal policy logic"-type constraints.
8. verbatim_copy[] — every exact UI string the doc hands over (banner text, modal copy, labels). These are gold — the prototype uses them verbatim. Quote precisely with the surface it belongs to. If a string contains a customer name, redact it (replace with [customer]) and mark it redacted — never emit the removed name, even in verbatim copy.
9. scope — in_scope[], out_of_scope[], phased{} (Phase 0 / Phase 1 / TBD).
10. open_design_questions[] — copy the doc's own "Open Design Questions / Design Phase Questions" verbatim (genericized). These become the backbone of the assumptions ledger and the clarification round — surface them, never silently answer them.
11. dependencies[] — what this feature leans on (other attributes systems, engines).
12. inference_boundary — a short list of what the prototype will have to invent because the doc is silent (layout, component choice, exact copy where absent, click-level flow). Be honest and specific.

Step 5 — Emit

Emit (a) a readable markdown extract for humans and (b) a machine block for scene-mapper.

Output Format

Validate the slug first — kebab-case single segment, derived from the genericized title (never a customer name), rejecting separators/.. — and confirm the resolved output path stays under prototype-runs/. Then write to prototype-runs/<slug>/00-prfaq-extract.md: the readable extract, then a fenced json block:

{
  "prfaq_extract": {
    "slug": "...",
    "format": "classic | themed | prfaq+requirements | t3",
    "meta": { "feature_name": "...", "status": "...", "updated": "...", "author": "...", "tier": "...", "strategic_framing": "..." },
    "problem": "...",
    "solution_concept": "...",
    "actors": [ { "role": "...", "acts_on": "config | runtime | both", "provenance": "extracted | inferred" } ],
    "surfaces": [ { "name": "...", "anchor": "system-console | channel-header | ... ", "provenance": "extracted | inferred" } ],
    "capabilities": [ { "name": "...", "controls_what": "...", "disposition": "...", "phase": "...", "source_note": "(genericized)" } ],
    "behavioral_rules": [ { "rule": "...", "states": ["denied", "..."], "provenance": "extracted | inferred" } ],
    "verbatim_copy": [ { "text": "...", "surface": "...", "redacted": false } ],
    "scope": { "in_scope": [ "..." ], "out_of_scope": [ "..." ], "phased": { "phase_0": [ "..." ], "phase_1": [ "..." ], "tbd": [ "..." ] } },
    "open_design_questions": [ "... (verbatim, genericized)" ],
    "dependencies": [ "..." ],
    "inference_boundary": [ "..." ],
    "contradictions": [ { "a": "...", "b": "...", "resolution": "superseded-by-date | superseded-by-strikethrough | unresolved" } ],
    "scrubbed_customer_refs": [ { "token": "a customer", "context": "seat-expansion driver" } ],
    "placeholders": [ { "field": "meta.updated", "reason": "..." } ],
    "placeholder_prfaq": false,
    "source": { "source_type": "local | github | google-doc | confluence | mattermost-thread | web | pasted | <service>", "source_kind": "prfaq | discussion", "url": "...", "revision": "...", "context_paths": [] }
  }
}

Never put a real customer name in this output. Never resolve an open_design_question — carry it forward.

Error Handling

Error	Cause	Resolution
PRFAQ_NOT_FOUND	prfaq_path does not resolve	Stop; report the path and ask the user for the correct one (do not go hunting other systems).
EMPTY_OR_STUB	File is a placeholder-only stub (e.g., "[Placeholder — Keith can generate…]")	Extract what exists; flag placeholder_prfaq: true so the analyst raises a heavier clarification round to fill gaps.
UNRESOLVED_CONTRADICTION	Two load-bearing claims conflict with no tie-breaker	Record both in contradictions[]; do NOT choose — hand to the analyst as a clarification.
CUSTOMER_NAME_LEAK	A customer name would appear in output	Scrub to a generic role and log in scrubbed_customer_refs[]. Non-negotiable.

Tone & Calibration

• Faithful, not creative. Extract; don't design. The parser's value is a clean separation of stated vs. inferred.
• Honest about gaps. A short, accurate inference_boundary beats a padded one that pretends the doc said more than it did.
• Preserve verbatim copy exactly. Quoted UI strings are the highest-value extractables.

Related Skills

• scene-mapper — consumes this extract to derive the screen inventory, option divergence axes, and assumptions ledger.
• clarification-protocol — the analyst uses the open_design_questions + contradictions this parser surfaces to build its round.
• t3 (internal-product-knowledge) — the authoritative reader/writer for T3 docs; this parser only detects and reads T3 shape, never authors it.

---

Last Updated: 2026-09-09 Maintainer: Mattermost Design Team