Skip to content

SA Review Guide — Confluence-Imported Features

This guide is for Solution Architects reviewing features that were imported from Confluence into EFSpecCatalog via the classification pipeline. Your job is translation accuracy — does the catalog entry correctly describe what ExpertFlow actually ships?

This is not a commitment process. You are not approving features for development. You are validating that the product documentation is correct.

What you are reviewing

Each imported feature is a folder under features/{domain}/{feature-id}/ containing:

  • _index.md — identity node (id, name, domain, source_seed). Rarely needs editing.
  • perception.md — the translated Confluence description. This is what you review.

The derived_status will be yellow for all imported features. That is correct and expected — it means "documented from Confluence, awaiting SA validation." Do not try to change it.

The review workflow

Step 1 — Read perception.md

Open perception.md and check:

  • Demand signal: Does it accurately describe what the feature does and who uses it?
  • Initial scope: Is the "In scope" list correct for what ships today?
  • Confidence: The confidence field is low | medium | high. Low-confidence entries need more scrutiny — the LLM may have inferred incorrectly from vague Confluence content.

Step 2 — Cross-check against Confluence

The derived_from field in perception.md lists the source Confluence page ID(s). Open those pages to verify the translation is accurate.

derived_from:
  - "confluence:page/12345678"

Use the Confluence page as the ground truth. If the catalog description contradicts the Confluence page, trust Confluence (for now) and correct the catalog entry.

Step 3 — Correct if needed

Edit perception.md directly. Focus on: - Fixing inaccurate descriptions - Completing the "Out of scope" section if blank - Adjusting the domain if the feature was misclassified (also update _index.md → domain:) - Adding implementation_stack to _index.md if you know it (e.g. [Microsoft Dynamics 365])

Step 4 — Signal approval

Set reviewed_by in perception.md frontmatter to your email and commit:

reviewed_by: "[email protected]"

That is all. No other status change is needed.

What NOT to do

  • Do not create design.md, commitment.md, or delivery.md for imported features. Those artifacts are for the forward planning process, not historical documentation.
  • Do not change derived_status — it is CI-computed and will reset on next push.
  • Do not mark a feature green. Green requires a management commitment reference (commitment_ref). Imported features stay yellow until formally committed to a delivery plan.
  • Do not delete a feature because it seems redundant. Flag it with a comment instead.

Review queue

The classification pipeline produces a review queue sorted by confidence score (ascending). Start with the lowest-confidence entries — those are the most likely to need correction.

The queue file is at: design-artifacts/confluence-import/review-queue.yaml

Questions?

If a Confluence page describes something you don't recognise as a real shipped feature, or if the domain assignment is unclear, flag it in the queue file:

- feature_id: cti-crm-00045
  flag: "unclear — this describes a Cisco-specific customisation, not a general feature"
  flagged_by: [email protected]

Andreas or the catalog steward will triage flagged entries.