Official User Guide - v1.0.0

Feed the Troll

A gamification app for Jira Cloud. Your real Jira work earns XP, evolves a personal troll, and shapes a shared team village. Every number on this page reflects the exact values used by the app.

Getting Started

Feed the Troll is a Jira Cloud app installed from the Atlassian Marketplace by your Jira System Administrator. It surfaces in four places inside Jira:

Issue Context Panel - the right-hand context panel visible on every issue; your main hub for troll management, appearance, quests, and privacy settings
My Troll Status - an optional dashboard gadget you can add to any Jira Dashboard
Troll Village - a full project page showing the shared team village at Your Project > Feed the Troll Village
Feed The Troll Administration - the global admin page for Jira System Administrators

First-Time Setup

Ask your Jira System Admin to install Feed the Troll from Jira Settings > Apps > Find new apps.
Open any Jira issue. The Feed the Troll panel appears on the right. Click "Hatch Your Troll" to start onboarding.
Choose your Lineage (one of 15 types) and give your troll a name. Your choice shapes XP bonuses for the next 30 days.
Do your normal Jira work. XP is awarded automatically in the background - no manual tracking required.
View your troll's village at Your Project > Feed the Troll Village in the project sidebar.

Secure by design: Feed the Troll runs entirely on Atlassian's infrastructure. No data leaves Atlassian's cloud and no third-party servers are involved. Your troll data is stored with platform-enforced isolation.

Earning XP

Feed the Troll listens to 8 Jira event types and awards XP automatically. The formula is:

Total XP = floor( baseXP × qualityMultiplier × (1 + typeBonus) )

Base XP & Anti-Gaming Limits

All values below are the exact numbers used by the app.

Event	Base XP	Daily Cap	Cooldown
Log time on an issue	15 XP	4 / day	60 min
Transition an issue status	10 XP	8 / day	30 min
Flag an issue as blocked	20 XP	3 / day	2 hr
Comment on an issue	8 XP	6 / day	15 min
Sprint completed (team event)	50 XP	1 / day	None
Receive kudos from a teammate	10 XP	5 / day	5 min
Send kudos to a teammate	5 XP	3 / day	5 min
Update a time log	5 XP	4 / day	30 min

Silent caps: When a daily cap is reached, no XP is awarded and no error is shown. The troll simply stops eating until the next day (resets at midnight UTC). No punishment.

Quality Multipliers

Certain good habits award bonus multipliers on top of the base XP.

Event	Condition	Multiplier
Time logged	Logged on the same day you did the work	1.5× → 22 XP
Status transition	Moved to "In Progress" status	1.3× → 13 XP
Status transition	Moved to "Done" (or Closed / Resolved)	2.0× → 20 XP
Status transition	Moved to "Done" on an issue sitting in backlog 30+ days (Dusty Ticket)	2.5× → 25 XP
Blocker flag	Flag a blocker AND add a comment explaining it	2.0× → 40 XP
Comment	Comment on someone else's issue	1.5× → 12 XP
Sprint completed	Sprint completion ≥90%	2.0× → 100 XP
Sprint completed	Sprint completion ≥70%	1.5× → 75 XP

Evolution & Levels

Every troll has a level driven by cumulative XP. The XP threshold to reach level L is:

XP required = floor( 50 × L^1.5 )

Hatchling

1–4

0–558 XP

Youngster

5–9

559–1580 XP

Adult

10–19

1581–4471 XP

Elder

20–49

4472–17676 XP

Legendary

50+

17677+ XP

Milestone levels from the formula: Level 5 = 559 XP • Level 10 = 1,581 XP • Level 20 = 4,472 XP • Level 50 = 17,677 XP. At each stage boundary your troll's sprite and evolution name change, unique per Lineage.

The 15 Lineages

Choose your Lineage during onboarding. It sets your XP bonus multipliers per event type. You may change it once every 30 days from the Issue Context Panel. All bonuses are additive to the quality multiplier. Changing your lineage does not reset your level.

All 15 lineages are available to every team member — role labels are suggestions only, not restrictions.

All Lineages

Time logged+10%
Status changed+10%
Comment created+10%

Time logged+30%
Time log updated+20%

Status changed+25%
Sprint completed+20%

Comment created+30%
Kudos received+20%

Worklog, Status, Comment+5% each

Status changed+25%
Time logged+15%
Comment created+10%

Comment created+30%
Blocker flagged+25%
Status changed+15%

Sprint completed+40%
Status changed+20%
Comment created+15%

Sprint completed+50%
Blocker flagged+30%
Kudos received+20%

Comment created+25%
Status changed+20%
Time logged+15%

Status changed+30%
Blocker flagged+25%
Time logged+15%

Comment created+30%
Status changed+25%
Kudos received+20%

Comment created+30%
Time logged+20%
Status changed+10%

Status changed+25%
Sprint completed+20%
Time logged+10%

Sprint completed+40%
Status changed+20%
Comment created+15%

Troll States & Streaks

Your troll's state (visible in the Issue Context Panel sprite and animation) is determined by your recent activity. States are strictly upward - the only downward transition is to sleeping, which is peaceful and non-punitive.

State	Condition	Transition to next
Sleeping	3+ days since last Jira activity	Any activity → Awake
Awake	Active today, streak < 3 days	Streak ≥ 3 days → Thriving
Thriving	Active, streak ≥ 3 days	Level up → Celebrating (30s)
Celebrating	Level-up event (temporary, ~30 seconds)	Auto-returns to Thriving or Awake

Streak Logic

Streaks track consecutive days with any Jira activity. The key rule: streaks pause, they never reset.

Active yesterday → streak +1
Active today already → no change
Missed 1+ days (holiday, weekend) → streak stays the same (paused)
First ever activity → streak = 1

No punishment: There is no "sick", "sad", or "dying" state. Missing a week of work simply pauses your streak. When you return, your troll wakes up and picks up exactly where it left off.

Quests

Feed the Troll has three tiers of quests: Personal Quests you activate yourself, Team Quests generated each sprint, and Seasonal Quests tied to time-limited events. You can have up to 3 personal quests active at once. Completing a quest awards bonus XP and may unlock a collection item. Manage your personal quests from the Issue Context Panel.

Worklog Warrior

Log time on 5 different days

75 XP reward Unlocks: Hard Hat Min Level 1

Blocked Guardian

Flag 3 blockers to protect the village

60 XP reward Unlocks: Shield Tool Min Level 1

Comment Helper

Comment on 10 issues to help your team

80 XP reward Unlocks: Speech Bubble Hat Min Level 1

Status Keeper

Update 20 issue statuses this sprint

100 XP reward Unlocks: Clipboard Tool Min Level 1

Estimation Sage

Complete 5 issues within ±20% of estimate

125 XP reward Unlocks: Wizard Hat Min Level 5

Streak bonus: While on a streak, you earn +10% bonus XP for every 7 consecutive days, stacking up to +50%.

Team Quests

Team Quests are generated automatically at the start of each sprint. The whole team contributes progress together. Examples include Spring Cleaning (close aging stale issues), Flow Masters (keep work-in-progress under control), Sprint Warriors (hit 70% sprint completion), and All Hands on Deck (team-wide activity). Higher-tier variants like Deep Clean and Sprint Champions demand more but reward more.

Seasonal Quests

Four times a year, limited-time seasonal events appear with exclusive quests and cosmetic rewards. Each season runs for exactly one month and offers 3 unique quests that any troll can attempt.

Season	When	Quests	Exclusive reward
Frostbite Festival	December 1-31	Build an Igloo (close 10 issues), Snowball Fight (send 5 kudos), Frost Walker (7-day streak)	Santa Hat cosmetic
Spring Bloom	March 1-31	Plant a Garden (log 8 worklogs), Pollinate (comment on 10 issues), Spring Cleaning (close 15 issues)	Bunny Ears cosmetic
Summer Splash	June 1-30	Beach Party (send 8 kudos), Surf the Wave (20 status transitions), Build a Sandcastle (10-day streak)	-
Harvest Moon	September 1-30	Harvest Time (close 12 issues), Bonfire Night (log 10 worklogs), Pumpkin Carving (send 6 kudos + 6 comments)	-

How it works: Seasonal quests appear automatically in your Quest tab when the season is active. Progress is tracked just like regular quests - your real Jira activity counts. Quests expire when the season ends, so complete them before the month is over. Exclusive cosmetics (like the Santa Hat or Bunny Ears) can only be earned during their respective season and are yours to keep forever.

Collection

The collection consists of 52 items across four categories. Items are equipped from the Issue Context Panel and appear on your troll's sprite.

Hats (17 items)

Hard HatQuest: Worklog Warrior
Speech Bubble HatQuest: Comment Helper
Wizard HatQuest: Estimation Sage
Viking HelmetLevel 5
Top HatLevel 10
Royal CrownLevel 15
Graduation CapLevel 20
Cowboy Hat14-day streak
+ 7 more...Various sources

Tools (15 items)

ShieldQuest: Blocked Guardian
ClipboardQuest: Status Keeper
+ 13 more...Levels, streaks & drops

Colors (8 items)

GreenDefault
Blue, Purple, BrownLevel gates
Red, Gold, Black, WhiteLevel or streak

Unlock Sources

LevelAutomatic at threshold
QuestComplete specific quest
StreakMaintain streak N days
KudosReceive N kudos from teammates
SeasonalLimited-time events
Tavern Loot DropRandom drop while working
SecretUndocumented ;)

Tavern Loot Drops

While logging work, leaving comments, or moving issues, there is a small chance a Tavern Loot Drop chest appears above your troll. Opening it rewards either bonus XP or a random item from the loot table.

Tier	Chance	Reward
XP Bonus	65 %	+25 XP
Common item	20 %	Level 3-10 hat or tool you don't already own
Uncommon item	10 %	Level 12-20 hat or tool you don't already own
Exclusive item	5 %	Loot-drop-only item (Witch Hat, Jester's Cap, Glowing Orb)

A drop can trigger at most once per day per project. If you already own all items in a tier, that tier falls back to XP instead.

Hidden items

Items obtainable only via Loot Drops are not shown in the Collection grid until you own them. The category counter (e.g. Hats 3/14) only counts items that have a predictable unlock path plus any loot-drop items you have already discovered. This means the counter never shows an item you have no direct way to earn.

The Village

Each Jira project has a shared Troll Village visible at Your Project > Feed the Troll Village. All team members' trolls appear here. The village has six building types, each with levels 0–5.

Buildings

Building	Max Level	Notes
Hut	5	First structure unlocked
Smithy	5	Defense & tools theme
Library	5	Knowledge & quests theme
Watchtower	5	Vigilance & blocker theme
Tavern	5	Social & kudos theme
Keep	5	Legendary tier fortress

Defense Score (0–100)

Calculated from team behavior. Starts at 50.

Aging issues (>7 days) −3 each Max penalty: −30

No aging issues +10 All issues are fresh

WIP overload −2 per excess Threshold: 2 per active troll (min 4). Max penalty: −20

WIP under control +5 Within WIP limit

Blocker flagged (weekly) +2 each Flagging is GOOD - communication. Max: +15

Team activity ≥70% +10 % of team with active trolls

Team activity <30% −10 Most trolls are sleeping

Prosperity Score (0–100)

Weekly team XP +1 per 100 XP Max: +20. Zero XP = −10

Sprint completion ≥90% +15 Based on story points completed

Sprint completion ≥70% +8 -

Sprint completion <50% −10 -

Avg team streak +1 per day Max: +10

Active troll count +2 per troll Max: +10

Sprint Raids

When a sprint is closed via Board > Complete Sprint, a Raid is triggered automatically. The outcome depends entirely on the village's Defense Score at the moment of sprint close.

D ≥ 60

Victory

Building upgrade available. Each troll earns 55–75 bonus XP (scales with defense score).

40–59

Stalemate

Village holds. No bonus XP, no building change.

D < 40

Damage

Highest-level building loses 1 level (cosmetic). Trolls are never harmed.

Victory XP: Every team member earns between 55 and 75 bonus XP, scaling with the defense score. A defense of 60 awards +55 XP per troll; a perfect 100 awards +75 XP.

All raids are logged and viewable from the Village page's history tab. The team can review per-sprint defense scores to identify trends.

App Behaviour

Feed the Troll ships with sensible defaults for every project. All features listed below are on by default. A Jira System Administrator can adjust these per-project through the administration tooling. Individual users cannot change these settings.

Feature	Default	What it controls
Leaderboard	ON	Shows top trolls by level in the village
Kudos	ON	Allows teammates to send and receive peer kudos
Team Quests	ON	Sprint-scoped shared quests generated each sprint
Sprint Raids	ON	Defense events triggered at sprint close
Seasonal Events	ON	Time-limited seasonal quests and exclusive cosmetics
Ethics Mode	OFF	Cooperative-only mode — see below
Max active personal quests	3	How many personal quests a user can have active simultaneously (range: 1–5)

Ethics Mode

When Ethics Mode is active for a project, the app automatically disables all competitive elements:

Leaderboard hidden — no individual XP or level rankings are shown, regardless of each user's own privacy settings
Kudos disabled — peer kudos sending and receiving are turned off entirely

Team Quests, Sprint Raids, and Seasonal Events remain fully active under Ethics Mode because they are collaborative rather than competitive.

Instance-wide: To activate Ethics Mode across all projects simultaneously, a Jira System Administrator can enable Global Harmony Mode in the Global Admin page (see below). Individual project overrides are not possible while Global Harmony Mode is on.

Privacy Controls

Every user controls their own visibility from the Issue Context Panel. Defaults are designed to be social-friendly while protecting detailed stats. Your troll data is stored with per-user isolation - even System Admins cannot see another user's private troll data.

Privacy Toggle	Default	What it controls
`Show my troll in village`	ON	Your troll appears in the team village scene
`Show my level to team`	ON	Your level is visible on the leaderboard
`Show my streak to team`	OFF	Your streak day count is visible to teammates
`Show my XP details to team`	OFF	Your total XP is visible to teammates
`Allow kudos from teammates`	ON	Others can send you kudos (+10 XP each)

Global Admin

A Jira System Administrator accesses the Feed The Troll Administration page at Jira Settings > Apps > Feed the Troll. Only users in the Jira System Administrators group can reach it.

Global Harmony Mode

When Global Harmony Mode is switched ON, it forces all projects into a cooperative-only experience:

Ethics Mode is forced ON for every project — per-project settings cannot override this
Leaderboards are hidden across all projects
Kudos are disabled instance-wide
Only village health, team quests, and raid outcomes remain visible - a pure co-op experience

Rollout Strategy

All Realms - all projects can use the app immediately (requires an active subscription)
Specific Provinces - restrict to specific projects you choose (good for pilots or phased rollout)

Free plan limit: Without an active subscription the app is limited to 2 projects and the All Realms strategy is unavailable. An active Atlassian subscription (including the free trial period) removes the project limit and enables All Realms.

Data & Licensing

All data is stored securely within Atlassian's infrastructure. Individual user data is never visible at the admin level. The System Admin can view aggregate statistics only (total trolls, total projects, XP event volume).

Marketplace licensing: Feed the Troll is a single-edition Paid via Atlassian (PvA) app. Without an active subscription the app runs in free-plan mode (up to 2 projects). An active Atlassian subscription unlocks unlimited projects — enforced automatically, no manual configuration required.