#1: [feature] Define researched fixed companion builds with verified equipment recommendations · anthodev/xeno-team-builder

🔢 Impact Version (SemVer)

MINOR

📝 Description

Replace heuristic companion Arts and Skills selection with a researched, fixed build for every playable character except Cross. Identify the recommendations that recur across independent sources, verify their mechanical validity in Xenoblade Chronicles X: Definitive Edition, and curate one coherent build per character with at most two TP-consuming Arts. Verify the Arms Manufacturers and armor types recommended for each character as part of the same work.

The current implementation already selects companion Arts and Skills using each companion's own strategy, rather than Cross's strategy. It prioritizes default Arts and generic strategy preferences; Skell mode can replace Skills. Manufacturer recommendations are explicitly heuristic strategy-level mappings, not verified character-specific equipment advice. The change is therefore a move to documented character-specific builds, not a confirmed fix for direct Cross-to-companion loadout coupling.

This ticket includes the research and implementation. The exhaustive research has not yet been performed; no community consensus is asserted here.

✅ Expected Behavior

Each non-Cross character has one canonical Arts/Skills build with a documented role, selection rationale and character-specific equipment recommendations. Changing Cross's class, weapons or build, changing teammates, or switching between primary/offensive/safe team recommendations must not rewrite that character's build. Team composition recommendations may remain contextual.

The canonical build is fixed. Existing progression restrictions still apply: unavailable Arts/Skills use explicit, ordered, character-specific progression substitutes, not dynamic strategy ranking. Once unlocked, the canonical choices apply. Language changes only presentation.

The two-TP-Art limit is strict for every companion, including progression substitutes. Use up to eight legal Arts, filling with non-TP Arts where available. Never add a third TP Art merely to fill all slots. Cross's current selection and TP policy remain outside this change.

Treat the existing Skell-mode Skill replacement explicitly during research. It must not silently rewrite the canonical build. Preserve Skell vehicle/package recommendations as a separate concern, and do not present ground-only Skills as active Skell benefits.

📋 [Feature] Acceptance Criteria

Exhaustive character research

Cover every companion in the current roster: Elma, Lin, Irina, Gwin, Doug, Lao, L, H.B., Alexa, Bozé, Celica, Frye, Ga Jiarg, Hope, Liesel, Murderess, Nagi, Phog, Yelv, Mia, Neilnail and Al. Cross is excluded.
Produce a per-character research matrix of candidate Arts, Skills, role, recommended equipment and sources. Record URLs, game edition, relevant claims, independent-source recurrence, disagreements and the final decision. Search character-specific guides and discussions as well as general build guides; deduplicate copied recommendations.
Prefer Definitive Edition evidence. Validate any Wii U-era advice against Definitive Edition mechanics. Distinguish AI-controlled companion recommendations from player-controlled or Cross-only setups.
Rank recurring recommendations, then verify the complete build's synergy, weapon compatibility, unlock conditions, Skill-slot count and AI suitability. Do not assemble an incoherent build by independently choosing the most-mentioned entries.
Document sparse evidence or conflicting sources honestly. A mechanically justified editorial choice is acceptable when no consensus exists, but must not be labeled community consensus.

Fixed Arts and Skills

Define one canonical, ordered Arts/Skills loadout and documented progression substitutes for every companion. Replace generic strategy-based selection for companions; do not retain a hidden dynamic fallback.
At equal companion progression, its Arts/Skills remain unchanged across Cross configurations, teammate changes, AUTO/manual placement and team recommendation variants. Remove runtime Skell Skill substitution of the canonical loadout.
Every emitted companion loadout contains no more than two TP-consuming Arts. Verify TP consumption from game data, including auras and support Arts; TP generation alone does not make an Art TP-consuming.
All selections and substitutes are legal for the character and progression, unique, within slot limits, and compatible with equipped weapons. The TP ceiling takes precedence over filling eight Art slots.
Preserve Cross's existing behavior and progression controls. Clearly explain unavailable canonical choices and their deterministic replacements.

Arms Manufacturers and armor

Verify manufacturer names, actual weapon/armor offerings, relevant attributes and availability against reliable game references. Do not treat the existing strategy-to-manufacturer specialty text as proof.
Recommend manufacturer(s) separately where weapon and armor needs differ. Provide an explicit armor type or weight recommendation per character, with stat/trait rationale tied to the curated build. If mixed pieces are justified, explain which pieces/types and why.
Check progression or unlock restrictions and provide documented alternatives when recommended equipment is unavailable. Avoid asserting that one manufacturer or the heaviest armor is universally best.
Display the character-specific manufacturer and armor advice, rationale and source references in the build card in English and French. Manufacturer specialty text alone does not count as an armor recommendation.

Integration

Both companion planning paths and the UI use the same curated data. Update role/scoring inputs so team recommendations do not claim benefits from discarded dynamic companion Arts or Skills. Any retained potential-capability metric must be explicitly distinguished from the equipped build.
Keep contextual team composition and replacement recommendations operational, using each character's fixed role/build. Update affected expectations rather than preserving scores produced by obsolete loadouts.
Update existing documentation/changelog with the fixed-build policy, source methodology and companion-only TP ceiling.

🔗 Affected Endpoints/Routes

/: team recommendations and character build cards.
No new API endpoint is required.

🧪 Tests to Add

Type	Coverage
Unit	Complete roster coverage; legal Arts/Skills and progression substitutes; weapon and slot constraints; strict two-TP ceiling, especially when fewer than eight legal non-TP fillers exist.
Integration	Companion loadout invariance across Cross configurations, team variants and placement; removal of mode-driven Skill substitution; scoring consistency with curated builds; unchanged Cross policy.
Manual UI smoke	Inspect representative companion cards and progression changes in EN/FR. Change Cross's build and confirm stable companion Arts/Skills and character-specific manufacturer/armor advice. Verify source links and separate Skell presentation.

Use the existing TypeScript test setup, not PHPUnit or Behat. Test meaningful selection and legality boundaries rather than copying the full curated dataset into snapshots.

⚙️ Constraints

Scope is all non-Cross characters, not a subset of popular companions.
Research and manufacturer/armor verification are completion requirements, not follow-up work.
No claim of an exhaustive search of the entire internet. Exhaustiveness means full roster coverage, a documented search corpus and explicit evidence gaps.
No online scraping at recommendation time. Store reviewed recommendations and provenance as project data.
No changes to Cross build selection, no new build editor, and no redesign of Skell packages.

⚠️ [Conditional] Impact on Existing Behavior

Companion selections, displayed equipment advice and contextual team rankings may change. Current generic preference selection and automatic Skell Skill replacement cease to determine companion loadouts. Existing progression restrictions remain supported.

🔍 [Conditional] Technical Context

src/data/companions.ts: current 22-character roster, default Arts, unlock ranks, weapons and Skill-slot limits.
src/lib/engine.ts: selectCompanionArts, selectCompanionSkills, planCompanion, applyTpArtBudget. The shared TP_ART_BUDGET is currently 3; overflow backfill can reintroduce TP Arts. Do not lower the shared constant and inadvertently change Cross.
src/lib/contextualEngine.ts: planCompanionForMode replaces Skills in Skell mode; evaluateCompanionContext currently scores potentialArts, not just displayed Arts.
src/data/arms.ts: heuristic armsManufacturers mapping by strategy and armsManufacturerSource.
src/lib/types.ts: companion and recommendation contracts.
src/components/BuildCard.tsx: current Arts/Skills and manufacturer display; add explicit character-specific armor guidance.

Suggested branch naming pattern: feature/fixed-companion-builds/companions/<ticket-number>.