TenantAtlas/specs/226-astrodeck-inventory-planning/research.md

Research: AstroDeck Inventory Planning for Website Rebuild

Decision 1: Inventory source boundaries are directory-driven and explicit

• Decision: Use current apps/website/src structure as the mandatory discovery boundary:
  • src/pages -> Page primitives
  • src/components/sections -> Section primitives
  • src/components/primitives, src/components/content, src/components/layout -> Component primitives
• Rationale: This matches how the website is already authored and prevents hidden omissions.
• Alternatives considered:
  • Inventory only referenced components in current routes: rejected because it misses available but currently unused candidates.
  • Inventory from screenshots/manual browsing only: rejected because it is incomplete and non-deterministic.

Decision 2: Include demo/template artifacts as first-class inventory entries

• Decision: Mark template/demo artifacts explicitly (e.g., demo-only) instead of excluding them.
• Rationale: Excluding them early hides available options and weakens auditability of later keep/adapt/remove decisions.
• Alternatives considered:
  • Exclude demo components from inventory: rejected because it creates selective inventory bias.

Decision 3: Suitability classes must be mandatory and exhaustive

• Decision: Every inventory entry receives exactly one suitability class:
  • A strong candidate
  • B adaptable candidate
  • C weak candidate
  • D non-candidate
• Rationale: Follow-up mapping specs require deterministic triage and cannot rely on narrative-only judgments.
• Alternatives considered:
  • Optional suitability scoring: rejected because it creates inconsistent coverage across entries.

Decision 4: Risk and candidate markers are additive, not substitutive

• Decision: Marker tags (e.g., visual-risk, semantic-risk, hero-candidate, trust-candidate) augment but do not replace required fields.
• Rationale: Tags improve queryability for later mapping while preserving normalized core attributes.
• Alternatives considered:
  • Use markers only, skip required fields: rejected because it is too ambiguous for cross-spec traceability.

Decision 5: Inventory output must be mapping-consumable by contract

• Decision: Define a logical OpenAPI contract for inventory publication and summary retrieval so downstream specs can reference stable structures.
• Rationale: A contractized shape increases consistency for future tasks and automation without introducing runtime implementation in this feature.
• Alternatives considered:
  • Freeform markdown only: rejected because downstream mapping extraction becomes error-prone.

Decision 6: Existing repo patterns favor normalized inventories with explicit classes

• Decision: Mirror existing repository planning patterns by using normalized entity fields, explicit classifications, and deterministic summaries.
• Rationale: Prior specs (040, 042, 045) consistently model inventory-like domains with strict fields and taxonomy semantics.
• Alternatives considered:
  • Introduce a novel inventory schema unrelated to existing specs: rejected because it adds unnecessary cognitive overhead.

Resolved Clarifications

• No unresolved NEEDS CLARIFICATION items remain.
• The technical stack and boundaries are sufficient for Phase 1 artifact design.