Menu
Use when designing, implementing, auditing, or fixing Hearts of Iron IV national focus trees.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when designing, implementing, auditing, or fixing Hearts of Iron IV decisions, missions, timed objectives, decision categories, and mission localisation.
Use when implementing or updating Chaos Redux events.
Use when expanding Chaos Redux event ideas into detailed specifications before implementation.
Use when creating, sourcing, processing, converting, organizing, wiring, or documenting visual assets for Chaos Redux.
Use when designing, researching, wiring, or documenting Chaos Redux super-events.
Use when coordinating custom Codex subagents for Chaos Redux implementation, asset production, super-event research, audits, active small patches, planning handoffs, or documentation work.
| name | hoi4-focus-trees |
| description | Use when designing, implementing, auditing, or fixing Hearts of Iron IV national focus trees. |
Use this skill when a task touches national focus trees, focus-tree loading, focus effects, focus layout, focus localisation, focus icons, focus AI, focus-tree documentation, or event-created country trees.
This skill is the detailed focus-tree source of truth for AGENTS.md. Keep the root AGENTS.md concise and put reusable focus-tree design, implementation, audit, and completion standards here.
Use this skill together with:
AGENTS.md for repository-wide ruleschaos-redux-events when the tree belongs to an eventhoi4-decisions-missions when focuses unlock, modify, or depend on decisions and missionschaos-redux-event-assets when focus icons, leader portraits, flags, or idea icons are requiredBefore editing focus files:
C:/Program Files (x86)/Steam/steamapps/common/Hearts of Iron IV/documentation.AGENTS.md.hoi4-decisions-missions when focuses unlock decisions, timed objectives, missions, or dynamic mechanics.Do not rely on memory for prerequisite behavior, layout behavior, AI syntax, or search filters.
HOI4 focus prerequisites are easy to invert.
This means OR:
prerequisite = { focus = a focus = b }
This means AND:
prerequisite = { focus = a }
prerequisite = { focus = b }
Use vanilla examples before changing complex prerequisite and mutual-exclusion structures.
A focus tree is not a list of rewards. It is the playable identity of a country.
A good focus tree gives the country:
A tree should not stay politically static unless the country is intentionally fixed by its concept.
Use path-level design unless the user explicitly asks for a focus-by-focus blueprint.
The spec usually defines:
The implementation agent owns:
The final tree must preserve the route logic and gameplay intent from the spec.
Large, playable, long-lived, or event-created countries need real focus trees.
A major tree should usually include:
Do not collapse everything into one political ladder.
Political, industry, and expansion are the minimum branch families, not a full large-country tree. Important countries should usually also have military, diplomacy, internal faction, intelligence or security, special mechanic, and late-game branches when their identity supports them.
Branches should not be isolated columns. Political choices should alter which expansion, industry, military, diplomacy, and decision paths are available. Industry should support military or expansion. Expansion should create political consequences. Diplomacy should affect both foreign aid and war options.
Every major branch needs a clear payoff.
Examples:
A focus should usually unlock new gameplay, not only stats. Strong focus rewards unlock decisions, missions, units, advisors, leaders, laws, claims, cores, war goals, buildings, events, mechanics, route access, or AI behavior. Flat modifiers are supporting rewards, not the main design.
Political routes should update the visible country package where relevant:
Leader changes require portrait handling. Real leaders use sourced portraits. Fictional leaders, councils, symbolic leaders, or high-chaos authorities can use generated portraits through the asset skill.
Expansion branches should create consequences. Claims, cores, and war goals should usually interact with diplomacy, factions, resistance, foreign guarantees, local leagues, legitimacy, threat, or postwar settlement decisions.
Industry branches should usually create visible map or production changes: factories, infrastructure, railways, supply hubs, forts, anti-air, airbases, dockyards, resources, production lines, or construction decisions.
Decision categories should evolve with focus progress. Early focuses may unlock basic decisions. Later focuses should add new targets, stronger actions, cheaper costs, new risks, or new mission families. A decision category should feel different after a route develops.
The fixed-purpose exception is narrow. A country is fixed-purpose only when its concept clearly cannot support normal politics, such as a death-state, machine-state, plague-state, or pure destruction actor. It still needs meaningful internal branches around method, hierarchy, economy, recruitment, expansion, and endgame.
A branch does not count as a real branch unless it has enough content to change gameplay.
A real branch should usually include:
A branch made of one or two generic focuses is not a branch. It is a support node.
Large-country branches should not be shallow labels. If a tree says it has a political branch, industry branch, expansion branch, military branch, or diplomacy branch, each of those branches must have enough content to be felt in play.
Do not leave large focus trees full of dead ends. A terminal focus is acceptable only when it is a real capstone, convergence point, failure state, route lock, formable completion, settlement outcome, late-game ambition, or deliberately optional side payoff.
A focus line has failed if it stops after a small modifier, an isolated national spirit, a token equipment grant, a generic stability reward, or a decorative political power payout. Side branches can end, but their final focus must feed back into the country identity, a decision family, a mechanic value, a new unit path, a map change, an advisor set, an expansion route, or another visible route payoff.
Do not create one-focus or two-focus spurs just to fill space. Merge them into a nearby branch, turn them into decisions, make them part of an idea lifecycle, or build them into a real side path with a clear purpose.
Every major branch should answer what the player does after finishing it. Good answers include a stronger decision category, a new diplomatic stance, a changed army system, postwar integration work, a formable route, a crisis response loop, a new expansion policy, or a late-game convergence path. A finished branch that only leaves the player with passive numbers is not enough.
Every major route needs route-specific AI strategy. AI should not only have generic focus weights.
AI should understand:
Every major route also needs a distinct localisation tone. A socialist route, military route, democratic route, nationalist route, religious route, machine route, death-state route, foreign client route, and high-chaos route should not sound the same.
Focus titles and descriptions should make the route identity clear without using generic filler language.
Expansion branches must define what happens after victory.
War goals alone are not enough. Expansion routes should include postwar handling such as:
Industry branches should be geographically grounded. Important factories, resources, ports, railways, supply hubs, forts, anti-air, and airbases should be tied to relevant states or named regions when possible, not granted only as abstract country-wide bonuses.
Advisor unlocks should match route identity.
Examples:
Large focus trees should include achievement hooks for difficult route completions, rare branch combinations, expansion outcomes, successful internal reform, avoiding foreign dependency, forming leagues, surviving high-chaos paths, or completing hard late-game ambitions.
For every major focus tree, the completion report must include a route coverage table comparing the spec's required routes against implemented routes.
Required table columns:
| Required route | Implemented route or focus branch | Status | Notes |
|---|
Missing, renamed, merged, simplified, fallback, or replaced routes must be reported.
A major route should leave visible evidence in the game. This can include map changes, new decisions, new units, new advisors, changed leader, changed flag, changed cosmetic name, new faction behavior, new focus availability, changed diplomacy, or a visible mechanic. A route that only changes hidden variables or tiny modifiers is not meaningful.
Large focus trees should have early, middle, and late pacing.
Every major route should have a tradeoff. A military route may reduce freedom or legitimacy. A foreign-aid route may increase dependency. An expansion route may create resistance or foreign backlash. An industry route may consume civilian capacity or weaken short-term defense. A high-chaos route may give power while damaging stability, diplomacy, or normal politics.
Do not overuse mutual exclusions. Mutually exclusive paths should represent real identity changes, strategic commitments, or incompatible institutions. Support branches like industry, army, diplomacy, and logistics should usually coexist unless the route logic says otherwise.
Important routes should define failure states. A failed political reform can empower radicals. Failed expansion can trigger backlash or settlement. Failed industry can create dependency. Failed foreign-aid balancing can create a client state. Failed military centralization can create rogue generals or militias.
Focus and decision localisation should tell the player the visible baseline effect of the route or action. It should not reveal hidden effects, secret outcomes, hidden variables, or future surprises. The player should understand what the focus visibly does, such as moving toward military rule, opening an industry program, unlocking a public diplomatic route, forming a League office, or preparing border claims, without being told about hidden follow-up effects.
Large focus trees should interact with the event or country special mechanic. A major tree should not sit beside the mechanic without changing it.
Special mechanic values can include:
Focuses should affect mechanic values directly when the country has such a mechanic. Political focuses can change legitimacy, balance of power, party strength, faction cohesion, or authority. Industry focuses can change industrial capacity, construction pressure, resource control, or economic recovery. Military focuses can change readiness, command obedience, recruitment, or defensive preparedness. Diplomacy focuses can change influence, recognition, sponsor pressure, faction cohesion, or foreign penetration. Expansion focuses can change threat, legitimacy, claims, resistance, local support, or faction goals.
Mechanic values should unlock or block content. A value should not only be a number. Values should affect focuses, decisions, missions, events, advisors, leaders, laws, factions, war goals, reforms, crises, or endings.
Important internal struggles should consider a balance of power or equivalent mechanic. Good balance-of-power conflicts include army versus parliament, factory councils versus ministries, monarchists versus republicans, foreign patrons versus national independence, security service versus civilian cabinet, or cult authority versus military command. Focuses and decisions should push the balance and unlock branch content, risks, leaders, laws, advisors, or events.
When a focus tree creates or leads a faction, league, bloc, compact, coalition, or alliance, that faction needs goals and rules. Define membership conditions, joining logic, refusal logic, expulsion logic where relevant, war goals, shared decisions, AI behavior, victory conditions, and failure conditions. Important event-created factions should usually have a mechanic such as cohesion, shared command, war council support, joint reserves, recognition, member confidence, sponsor pressure, or strategic goals.
Factions should not form too easily. Define minimum membership, crisis conditions, ideological compatibility, war pressure, diplomatic preparation, and regional logic.
Special mechanics must be visible somewhere the player can understand them. A mechanic can appear in a decision category header, custom scripted GUI, progress meter, scripted localisation tooltip, focus tooltip, national spirit tooltip, or a combination of these.
When a mechanic is important enough for a custom scripted GUI, consider visual presentation beyond static text. Useful presentation can include progress bars, meter fill variants, state icons, status frames, warning frames, selected and locked variants, animated frames, or frame-by-frame visual changes that make the mechanic feel alive. The visuals should clarify the mechanic, not clutter it.
Special mechanics can hide future surprises, but they should not hide basic cause and effect. The player should understand why a visible value rose or fell, which public action changed it, and what broad type of response is available.
AI strategy must respect route validity. AI should not pick a branch that requires a missing state, dead sponsor, non-existent faction, unavailable ideology, disabled evolution, impossible border, or absent enemy. Invalid routes should be hidden, bypassed, or weighted to zero.
A new playable country package must not be generic. It needs a specific identity, starting problem, political direction, map role, military style, economy, diplomacy, AI behavior, and at least one mechanic or decision family that makes it play differently from other new countries.
Shared trees are allowed, but they must be adapted. Shared trees need country-specific localisation, route names, decisions, AI weights, leaders, rewards, icons, and scripted localisation where relevant. If every country using a shared tree reads and plays the same, the tree has failed.
When a route changes leader, ideology, faction, cosmetic name, flag, advisor roster, or special mechanic identity, the focus-tree spec and implementation should account for the needed visible assets and whether they are reused, sourced, generated, or blocked.
Important mechanic thresholds, caps, gains, losses, duration bands, AI weights, and scaling values should be centralized in script constants or a clearly documented tuning file. Do not scatter magic numbers across focus files, decisions, events, scripted effects, and scripted triggers.
Avoid one-time reward dumps as the main design. A focus can give factories, units, equipment, resources, or buildings, but important focuses should often unlock a repeatable decision, timed mission family, production route, advisor, mechanic, route branch, or long-term gameplay system.
A one-time reward is acceptable when it fits the story and balance, but it should not be the main reward pattern of a large tree.
Before claiming completion, review the tree for exploits:
If an exploit is possible, fix it with limits, flags, dynamic costs, cooldowns, route locks, scripted triggers, AI limits, or one-time completion flags.
Focus trees that unlock many decisions should also define how those decisions are staged.
Do not unlock every possible decision at once. Large decision systems should use phases, caps, priorities, regional pools, route locks, or crisis-state filters so the player sees the decisions that matter now.
A decision category should feel curated by the current country route and campaign state, not like a debug menu.
Focuses can control clutter by:
Every large focus tree should have a distinct expansion, reunification, liberation, federation, settlement, or regional ambition branch.
This branch must be separate from the main political tree and separate from the industry tree.
The expansion branch should actually change the map or diplomatic order. It should not be a line of generic bonuses.
Good expansion branch effects include:
Expansion should follow the country's ideology, geography, trauma, economy, military doctrine, foreign patron, crisis state, or special identity.
Bad expansion branches:
Large focus trees must alter politics directly.
Political branches should include meaningful changes such as:
A country should not remain politically static through a major focus tree unless that is the explicit concept.
Examples of route families:
Fixed-purpose chaos countries can have narrower political design. For example, a country whose entire identity is death, plague, machine rule, or total destruction may have one ideological purpose. Even then, its tree should still create mechanical choices inside that purpose, such as doctrine, expansion method, internal hierarchy, recruitment, economy, and endgame ambition.
Focus rewards must be concrete and varied.
Do not make most focuses grant:
Use effects that change play.
Good rewards include:
Small numeric modifiers can support a focus, but they should not be the main point of most focuses.
Do not fairy dust a focus tree with many tiny bonuses and call it depth. A branch made from small pieces such as +2%, +3%, minor political power, tiny stability, tiny war support, small generic equipment, or slight production bonuses will feel meaningless.
A focus reward should usually do at least one of these things:
If a focus mainly gives a small flat modifier, the implementation must justify why that modifier matters. It can be acceptable as one part of a larger reward package, a frequent stack, a temporary crisis push, or a final adjustment to an existing mechanic. It is not acceptable as the whole reward for an important focus.
Do not scatter many tiny modifiers across a tree to create the appearance of progression. Combine weak rewards into fewer stronger focuses, convert them into staged idea upgrades, or replace them with decisions, missions, map changes, unit paths, advisors, mechanic thresholds, or route access.
Completion reports and focus audits must flag fairy-dust rewards. A route with many tiny standalone rewards should be treated as incomplete until the rewards are merged, strengthened, connected to a mechanic, or replaced with visible gameplay.
Do not create a new idea in every focus.
Use an idea only when it represents a lasting institution, doctrine, route identity, military structure, economic system, or crisis condition.
When an idea already represents the institution, later focuses should usually:
New or unstable countries should often start with a few negative or mixed ideas, then solve or transform them through the tree.
Examples:
Every important starting idea should have a lifecycle:
Do not use national spirits as easy badges for completing shallow focus lines. A national spirit should represent an institution, doctrine, crisis condition, political identity, economic system, military structure, foreign relationship, or special mechanic that changes how the country plays.
A major national spirit should not be earned by one easy focus with no cost, risk, prerequisite, route commitment, decision follow-up, or mechanic interaction. If the spirit is powerful, it should usually require a real path commitment, a branch milestone, a mission success, a crisis choice, a reform chain, a formable step, or a meaningful sacrifice. If the spirit is easy to obtain, it should be modest, temporary, narrow, or part of a larger staged system.
A national spirit is unrewarding when it has only a flat modifier and no lifecycle. Before adding a new spirit, decide whether the existing idea can be upgraded, modified, replaced, worsened, temporarily strengthened, or tied to decisions. Prefer a smaller number of deep spirits over a long list of shallow spirits.
Important national spirits should usually have at least two of these:
Reject a tree if it has many easy-to-achieve national spirits that feel unrelated, passive, or unrewarding. Merge them into one staged institution, convert some into timed modifiers, move some effects into decisions or missions, or require a stronger route commitment before granting them.
Focus trees and decision systems must not feel separate.
Focuses should unlock, modify, improve, or restrict decisions and missions.
Examples:
A focus that unlocks a decision family should state:
A decision family unlocked by focuses should reference the relevant route in docs and localisation.
A focus tree can prepare, reveal, enable, or stabilize a formable nation, but the final formation should usually be handled by a decision when state control matters. Use focuses to build the political claim. Use decisions to verify the map and perform the formation.
A formation route in a focus tree should define:
Do not make a formable route a linear claim ladder by default. The best formation routes usually combine legitimacy, state control, diplomatic recognition, military readiness, local integration, and a visible identity change.
When mapping a focus tree that can form countries, include a formation lane or route overlay in the architecture map.
Useful formation lane structure:
The tree should state whether the formable is:
For shared event-created trees, formables must use origin and package checks so unrelated countries do not receive the wrong route.
Focus rewards can:
Focus rewards should not:
Focus trees should consider animated portraits or animated route emblems for major political transformations. Use them for route payoffs such as a supernatural leader reveal, a restored dynasty, a revolutionary cult, a final formable proclamation, or a high-chaos state identity.
Animated portraits need static fallbacks. They should be assigned through the same leader, character, or cosmetic identity logic as the route itself. Real historical portraits require sourced material and careful treatment. Fictional or symbolic leaders can use generated animated portrait packages through the asset skill.
Do not make every leader animated. Animation should signal a special route, a high-chaos identity, a super-event-level transformation, or a rare hidden outcome.
Use mutual exclusions when the country's identity changes.
Good mutual exclusions include:
Do not use mutual exclusions for branches that should logically coexist, such as army and industry.
When a route becomes impossible, use bypasses or availability logic cleanly.
The tree must be readable in game.
Required layout checks:
If an available = { has_completed_focus = ... } condition gates a focus, decide whether it should also be a visible prerequisite. Do not add a visible prerequisite if it creates crossing lines. Move the branch or redesign the gate.
When an event creates or releases a country, set a flag showing that the event created that country.
Only load or replace a runtime focus tree if the event actually created the country.
Existing countries with their own meaningful tree should usually receive additive crisis branches, decisions, ideas, or events, not a blind tree replacement.
For every event-created country, verify:
Every major route needs AI behavior.
AI should consider:
Avoid flat AI weights when campaign state matters.
AI should not accidentally choose suicidal or nonsensical routes just because they are visible.
Every focus needs:
Every political route needs localisation that makes the route identity clear.
Leader changes require leader portraits. Real leaders use sourced portraits. Fictional leaders and symbolic councils can use generated portraits through the asset skill.
Flag or cosmetic-name changes require flag and localisation coverage.
When an improvement addendum deepens a focus tree, preserve the route idea before adding nodes. The goal is not a longer tree. The goal is a sharper country identity, stronger branch interaction, clearer route locks, better rewards, stronger AI, and more visible consequences.
Formation routes should usually combine focus preparation with a decision that verifies state control. Focuses can discover old claims, call a congress, unlock a seal, prepare integration, recruit elites, expose a hidden identity, or open the formation decision. The decision then checks the map and performs the formation.
Hidden formables can be routed through secret focuses, events, leader changes, chaos tiers, ancient artifacts, internal factions, or custom GUI investigation. Hidden content should still have a full implementation handoff. It needs reveal logic, visibility rules, localisation, assets, AI handling, post-formation gameplay, and disqualifiers.
Animated leader portraits and animated route emblems should be reserved for major transformations. Use them when the route payoff changes the country's identity, reveals a high-chaos leader, forms a new state, or completes a dramatic ideological break. Keep a static fallback and ensure the animation has a clear trigger and cleanup state.
Focus tree subagents are active small-patch agents by default inside the current task scope. They can patch prerequisite fixes, mutual exclusion fixes, bypasses, route locks, AI weights, icon references, focus filters, localisation keys, small reward variety, existing decision hooks, and existing formable unlock hooks without waiting for a separate permission prompt.
They should not redesign a whole tree, add a full route family, create a new formable chain, or change the country identity. When the tree needs broader depth, they should write an improvement plan under docs/plans/<event_id>_<event_slug>_plans/ and leave implementation to the main agent.
Every patch must write a handoff with changed files, changed focus ids, route behavior before and after, meaningful validation, skipped task-specific validation, and remaining route risks.
For large focus-tree work, update documentation.
Include:
Before completion, audit:
A focus tree task is complete only when:
If a tree uses a fallback tree where the spec requires a bespoke tree, report it as a simplification.
If no simplifications were made, say so and provide evidence.