Skip to main content

Feature Catalog

Purpose​

Provide a reviewer-friendly catalog of portfolio-app features with consistent, evidence-backed documentation. This section explains how feature pages are organized, what each page must contain, and how to validate claims.

Scope​

In scope​

  • feature groups aligned to the feature inventory
  • feature page governance and required fields
  • validation expectations for each feature

Out of scope​

  • project dossier content (see 60-projects)
  • roadmap and issue tracking (see 00-portfolio/roadmap)

Prereqs / Inputs​

  • Portfolio App feature inventory exists and is up to date
  • ADRs, runbooks, and reference docs exist for cross-linking
  • Feature owners follow the standard page shape

Procedure / Content​

Feature groups​

Feature page governance​

Every feature page must follow the repository standard page shape:

  1. Purpose
  2. Scope
  3. Prereqs / Inputs
  4. Procedure / Content
  5. Validation / Expected outcomes
  6. Failure modes / Troubleshooting
  7. References

In Procedure / Content, include the required feature fields:

  • Feature name
  • Feature group
  • Technical summary
  • Low-tech summary
  • Feature in action
  • Manual confirmation process
  • Potential behavior if broken or misconfigured
  • Long-term maintenance notes
  • Dependencies, libraries, tools
  • Source code references (GitHub URLs)
  • ADRs
  • Runbooks
  • Additional internal references (exclude /60-projects/portfolio-app, /00-portfolio, /roadmap, and /issues)
  • External reference links (official docs only)

Use the standard feature template at docs/_meta/template/template-feature-details.md when creating new feature pages.

Validation / Expected outcomes​

  • Each feature page is easy to audit within 2 to 5 minutes.
  • Claims on each feature page are supported by references or validation steps.
  • Feature groups remain aligned with the feature inventory and roadmap.

Failure modes / Troubleshooting​

  • Feature pages read like marketing: add validation steps and concrete evidence.
  • Claims lack references: add ADRs, runbooks, or reference docs.
  • Stale feature descriptions: update in the same PR as the app change.

References​