ImpactLoop Documentation

Overview

ImpactLoop combines project telemetry, structured decision logs, and automated nudges so teams can keep work flowing without leaving Jira Cloud. Everything runs within Atlassian’s Forge platform, so data remains inside your tenancy.

Key capabilities

• Done review comments triggered only when material phase outliers are detected.
• Queue-backed nudges that watch stalled review and WIP states and auto-clear when work moves.
• Weekly digest snapshots highlighting trends, aging work, and backlog health.
• Structured decision telemetry and metrics stored securely in Forge data storage.

Audience

• Jira administrators responsible for installing and configuring Forge apps.
• Delivery leads who monitor flow efficiency and want data-backed insights.
• Support engineers who maintain ImpactLoop and triage incidents.

1. Getting Started

System requirements

• Jira Cloud site with global permissions to install Forge apps.
• Atlassian Forge CLI for administrators who deploy from source.
• Recommended browser support: latest Chrome, Firefox, Safari, and Edge.

Installation (Marketplace)

1. Navigate to Atlassian Marketplace → search “ImpactLoop”.
2. Click “Try it free” or “Install”, then select the target Jira Cloud site.
3. Grant requested scopes (read:jira-work, write:jira-work, storage:app).
4. The app appears under Jira project settings in the ImpactLoop section.

Installation (Forge deploy)

1. Clone the repository and run pnpm install.
2. Authenticate with forge login.
3. Deploy via pnpm --filter @forge-factory/impactloop run deploy:dev.
4. Install to the development site with forge install.
5. Promote to staging or production via forge deploy and forge promote.

Upgrading

Marketplace customers receive automatic updates. Review release notes posted in the repository under docs/releases. Self-hosted administrators should redeploy new versions and re-run settings validation in each Jira project.

2. Permissions & Data Access

Scopes

• read:jira-work: read issue fields, changelog entries, and status metadata.
• write:jira-work: post comments and add worklog entries when required.
• storage:app: store baselines, settings, and decision logs in Forge storage.

Data residency

ImpactLoop uses Forge-hosted storage exclusively. No external databases or telemetry pipelines are involved, and settings, metrics, and decision history remain within your Atlassian tenancy.

Data retention

Project settings and baselines persist until an administrator deactivates the app or requests deletion. Temporary nudge queues and debug payloads auto-expire per retention schedules (default 72 hours). Uninstalling clears Forge storage within 30 days; contact support to expedite removal.

3. Configuring ImpactLoop

Accessing settings

Open Jira project → Project settings → ImpactLoop Settings. ImpactLoop auto-detects project context, and only project administrators can change configuration.

If your Jira space lists apps in Space settings, you can also open Space settings → Apps → ImpactLoop Settings to customize phases, nudges, and digest delivery from the app panel.

Initial configuration workflow

1. Select phase catalog: choose a template (Software, Marketing, Sales) or custom mapping.
2. Map statuses: assign each Jira status to a phase or mark it intentionally unmapped.
3. Baseline strategy: set lookback windows and minimum data samples.
4. Materiality thresholds: adjust noiseThresholdPct and materialityFloorMinutes to control comment sensitivity.
5. Auto-comment: enable comments on Done transitions, optionally configure silent mode.
6. Nudge policy: define thresholds for review pickup and aging WIP nudges.
7. Digest delivery: toggle the weekly digest and set the housekeeping issue key.
8. Save settings; auto-save triggers produce success toasts and log changes.

Settings reference

• phaseCatalog: structure describing phases, labels, and intents.
• silentMode: disables outbound comments while retaining analysis and logging.
• commentRateLimitHours: minimum hours between comments on a single issue.
• nudges.reviewPickup.thresholdHours: triggers when review wait exceeds this threshold.
• digest.issueKey: Jira issue receiving the weekly digest comment.

Each setting is validated client-side (type and range) and sanitized server-side for safety.

4. How ImpactLoop Works

Issue-updated workflow

1. A trigger listens for status changes to Done.
2. ImpactLoop fetches project settings, ensures baselines are available, and evaluates the completed issue.
3. Materiality checks filter noise; if an outlier exists, ImpactLoop posts a structured comment summarizing top phase variances.
4. The decision is recorded (comment-posted, no-insights, already-commented, and more), and metrics are incremented.

Finalization queue

If an issue cannot be fully analyzed immediately (for example, baselines are warming), ImpactLoop enqueues a finalization job. An hourly scheduler retries analysis until baselines stabilize or maximum attempts are reached.

Nudge scheduler

Storage tracks when issues enter key statuses. The hourly job processes due nudges, comparing elapsed duration to thresholds. Nudges use idempotency markers to avoid duplicates, and processed items update metrics.

Weekly digest

The weekly trigger aggregates project-level metrics such as lead time trends, aging issues, and backlog health. ImpactLoop posts to the configured issue key or stores the summary for review in the settings UI.

Decision telemetry

Each automation (comment, nudge, skip) yields a decision record with a correlation ID, reasons, and metadata. The project settings panel shows the latest decision state, and backend logs provide audit entries labelled as impactloop decision markers.

5. Observability & Logging

Client logging

The React settings app logs major actions (loading settings, saving changes, running digests) via console.info and console.error. Entries include change counts and identifiers to aid support teams.

Function logging

Backend functions use structured helpers (logInfo, logWarn, logError) so entries appear in Forge logs with context. Each invocation records project IDs, actions, branch outcomes, and sanitized error details.

Accessing logs

• Marketplace admins: Atlassian Admin → Manage Apps → ImpactLoop → Logs.
• Developers: forge logs --tail or the Atlassian developer console. Filter on keywords such as finalize-pending or Nudge comment posted.

Metrics & health

metrics:v1 counters track comment volume, skipped decisions, and nudges processed. Use the settings UI Metrics card to review aggregated stats and detect anomalies.

6. Troubleshooting

No comments posted

• Check project settings to confirm auto-comment is enabled and silent mode is off.
• Review logs for no-insights or MATERIALITY_NOT_MET outcomes; adjust thresholds if needed.
• Confirm baselines warmed: the baseline section should show sample counts above the minimum.

Excessive nudges

• Inspect nudge thresholds and consider increasing fallback hours or disabling specific nudge types.
• Verify statuses are mapped correctly; misaligned phases can produce inaccurate timers.
• Review logs for threshold logic markers such as threshold-not-met or threshold-increased.

Weekly digest missing

• Ensure the digest is enabled and the issue key is valid for comments.
• Check logs for Weekly digest comment failed or Manual digest failed.
• Run a manual digest from the settings UI to confirm configuration.

Forge errors

• ForgeError: Storage quota exceeded: clear debug storage keys or contact support.
• Missing scopes: reinstall the app to grant necessary scopes.
• Project access issues: update API tokens or confirm the project remains active.

Performance considerations

ImpactLoop processes transitions asynchronously, so large projects might see short delays before comments post. High-churn projects should monitor Forge invocation limits and contact support for rate-limit strategies.

7. Security & Compliance

Data security

All Forge-stored data is encrypted at rest and in transit. ImpactLoop relies on Atlassian-managed TLS and does not send data to external processors.

Access controls

Only site administrators can install or uninstall ImpactLoop. Project administrators manage settings, and internal support access to logs is role-based and audited.

Privacy

ImpactLoop processes Jira issue metadata, user display names, and comment bodies as required for functionality. See our site privacy policy for current terms.

Incident response

Monitoring alerts when Forge logs include repeated errors or failures. Incidents are escalated within 24 hours, and impacted organizations are notified per Marketplace requirements.

8. Best Practices

Calibration

Start with default thresholds. After two weeks, review comments and adjust materiality floors to match team tolerance. Resolve unmapped statuses to maintain baseline fidelity.

Change management

Communicate ImpactLoop rollout to teams, share sample comments, and highlight nudge behavior. Use the weekly digest during sprint reviews or operations meetings.

Observability habit

Treat missing logs as defects. Add instrumentation when extending functionality and capture correlation IDs from comments to trace decisions.

Testing

Use a Jira sandbox or development site to validate new configurations. Run pnpm --filter @forge-factory/impactloop run test before deployment.

9. Support & Contact

Support channels

• Email: support inbox
• Issue tracker: link provided in the Marketplace listing.
• SLA: one business day response for critical incidents, three days for functional questions.

Feedback & roadmap

Submit feature requests via the issue tracker. Roadmap updates publish quarterly on the documentation site, and beta features are flagged within the settings UI with opt-in instructions.

10. Glossary

• Baseline Mode: indicator of confidence in current metrics (warm, warming, fallback).
• Materiality Floor: minimum time delta in minutes required before an outlier triggers a comment.
• Nudge Marker: storage record preventing duplicate nudges during the cooldown period.
• Decision Record: immutable log entry capturing the outcome of an automated action.

Appendices

A. API Endpoints

ImpactLoop uses Forge built-ins such as @forge/api storage and property functions. No external REST endpoints are exposed. Document any custom extensions separately and ensure authentication coverage.

B. Deployment Checklist

• Run lint and automated tests.
• Verify Forge deployment output.
• Confirm logs show successful scheduled triggers post-deploy.
• Inform stakeholders about changes and update documentation revision history.

C. Revision History

Maintain a documentation change log with date, editor, and summary. Align updates with release notes for traceability.