BTA Docs / Analysis reference

What BTA measures

Beyond The Alignment reads the work record in GitHub or GitHub Enterprise and organizes it into evidence that can support planning. This reference explains the fields BTA reads, the metrics it calculates, and the limits of what those metrics can say.

Metrics are information, not decisions.

A pattern can show where to ask a better question. It does not explain cause, rate a team, or replace the context held by the people doing the work.

Source fields

BTA uses repository and work-item data returned by the GitHub API. The available record depends on repository permissions, history, and the selected analysis scope.

Repository fields

Field	Meaning	Source
`num_pull_requests`	Total pull requests returned for the selected repository and scope.	GitHub API
`num_contributors`	Distinct contributors represented in the repository record.	GitHub API
`num_stargazers`	Current number of accounts that starred the repository.	GitHub API

Issue and pull-request fields

Field	Meaning
`id`, `number`	GitHub identifiers used to trace a result back to its source item.
`title`, `body`	The item title and description. These fields support search, word frequency, and topic analysis.
`state`	Whether the item is open or closed when the data is collected.
`user`	The GitHub account associated with the item.
`comments`	The number of comments recorded for the item.
`labels`	The labels applied in GitHub. Label quality and conventions vary by repository.
`created_at`, `updated_at`, `closed_at`	Timestamps used to describe volume, activity, age, and closure timing.
`time_to_close`	Elapsed time from creation to closure for a closed item. Open items do not have a completed close time.
`html_url`	The source link used to return a reader to the item in GitHub.

Core metrics

Core metrics are direct counts or repeatable calculations from the repository record. They describe what is present in the data. They do not explain why it happened.

Item count

Direct

The number of issues or pull requests in the selected repository, date range, and query scope.

Output: Whole number
Inputs: Items returned by the GitHub API

What it can tell youHow much recorded work exists in the selected scope.

What it cannot tell youEffort, complexity, quality, or whether every unit of work was recorded in GitHub.

Open and closed distribution

Calculated

The count and proportion of items in each GitHub state at the time of collection.

Formula: Items in state / all items in scope
Output: Count and percentage

What it can tell youThe visible balance between completed and still-open work.

What it cannot tell youWhether open work is blocked, abandoned, intentionally long-running, or still valuable.

Time to close

Calculated

Elapsed time between created_at and closed_at for closed items. BTA reports mean, median, minimum, and maximum values.

Formula: closed_at - created_at
Unit: Hours or days

What it can tell youWhether items tend to close quickly, slowly, or in separate timing groups. If many close quickly while others remain open for a long time, that pattern is worth examining.

What it cannot tell youWhy work took that long, whether speed was desirable, or how much active work occurred between the timestamps.

Resolution-time distribution

Calculated

Closed items grouped into elapsed-time ranges so the shape of closure timing is visible instead of being reduced to one average.

Inputs: Closed items with valid timestamps
Output: Count by time range

What it can tell youWhether work closes in one consistent range or is split between very short and very long durations.

What it cannot tell youWhether the ranges represent different work types, priorities, dependencies, or process problems.

Comment activity

Calculated

Total, mean, median, and maximum comment counts for items in scope.

Inputs: comments for each item
Output: Counts and summary statistics

What it can tell youWhere discussion is concentrated and which items may deserve closer review.

What it cannot tell youDiscussion quality, alignment, difficulty, or communication that occurred outside GitHub.

Activity over time

Calculated

Items created over time, cumulative volume, state changes, and activity grouped by day and hour.

Inputs: Creation, update, and closure timestamps
Output: Time series and heatmap counts

What it can tell youWhen recorded activity increased, decreased, or clustered.

What it cannot tell youCapacity, productivity, urgency, or the cause of a change in activity.

Contributor distribution

Calculated

The number of contributors and the share of recorded items associated with each contributor.

Formula: Contributor items / all attributed items
Output: Count and percentage

What it can tell youWhether visible work is broadly distributed or concentrated among a smaller number of accounts.

What it cannot tell youIndividual performance, expertise, ownership quality, invisible work, or whether concentration is appropriate.

Relationships and flow

Calculated

Views connecting items through labels, contributors, comments, reviews, time, or another shared field. Outputs can include matrices, label flows, timelines, and scatter plots.

Inputs: Normalized work-record data
Output: Matrix, flow, timeline, or scatter data

What it can tell youWhere relationships, handoffs, or unusual combinations appear in the recorded work.

What it cannot tell youOrganizational reporting lines, collaboration quality, or causation.

Text and topic analysis

BTA can organize the language in titles and descriptions to make a large record easier to inspect. These outputs depend on the text available in GitHub and the selected method.

Word frequency

Counts recurring terms after text preparation. It shows which words appear often, not why they appear or whether they are important.

Topic clusters

Groups items that use similar language. Cluster labels summarize shared terms and should be checked against representative source items.

Enhanced labels

When enabled, a configured model can propose clearer names for topic clusters. The label is model-assisted; the underlying items and terms remain the evidence.

Questions about the record

BTA can use retrieval for evidence questions or structured queries for counts and comparisons. Answers should retain their query or source route.

Experimental interpretations

These are optional analytical lenses developed to surface questions that conventional repository summaries may miss. They are heuristics, not standard measurements, scores, or conclusions.

Use these to direct investigation.

Keep the formula, thresholds, and assumptions visible. Validate the result with source items and team context before using it in a decision.

Closure timing split

Compares items closed within a short window with items that remain open beyond a long window. It highlights a possible split in how work moves, but does not identify the cause.

Language pattern

Compares selected maintenance-oriented and innovation-oriented terms in item titles. Results depend on the chosen vocabulary and how consistently titles describe the work.

Knowledge concentration

Reports the share of visible work attributed to the most represented contributors. It can prompt continuity questions; it is not a measure of individual value or performance.

Structural markers

Maps recurring topics or keywords to predefined planning categories. The rule-based mapping is a prompt to inspect the related work.

Effective capacity

Combines repository indicators using explicit weights and caps. This is an exploratory composite, not actual team capacity or a staffing recommendation.

Innovation tax

Compares selected maintenance and innovation language. The ratio describes that vocabulary model only; it does not measure innovation output.

Coordination-cost estimate

Applies stated team-size, compensation, and benchmark assumptions to model a possible cost. It is a scenario calculation, not an observed financial result.

Data handling and provenance

BTA runs in the customer environment. It retrieves the permitted GitHub record, normalizes it, stores a local cache, computes analysis outputs, and presents the results.

1
Retrieve
Read the selected record from GitHub or GitHub Enterprise with customer-provided access.
2
Normalize
Convert source responses into consistent repository and work-item fields.
3
Cache
Store retrieved data and generated vectors in local SQLite storage for reuse.
4
Calculate
Generate metrics, distributions, topic outputs, and source-linked views.
5
Present
Organize the evidence so people can examine it and decide what to do.

What to record with an analysis

Repository and query scope
Data-through date and collection time
Cache or API source and refresh status
Calculation version, thresholds, and configuration
Missing fields, permission limits, and known gaps

Model boundary

Core repository collection and metric calculation do not require a model to decide what the record contains. Optional features can use a model selected and configured by the customer.

Inside the customer environment

GitHub retrieval, normalization, local SQLite cache, metric calculations, and report serving.

Optional configured provider

Selected prompts or evidence may be sent for enhanced topic labels, synthesis, embeddings, or question answering.

The customer controls the provider, model, credentials, feature use, and the policies that apply to transmitted data.

How to read the results

Start with the scope

A metric describes only the repositories, dates, item types, and fields included in the analysis.

Return to the source

Use counts and patterns to locate representative items, then inspect the work behind them.

Ask what is missing

GitHub does not contain every decision, dependency, conversation, or contribution.

Add human context

Teams explain history, intent, constraints, and exceptions that repository data cannot establish.

Keep inference visible

Separate direct fields, calculated metrics, heuristic interpretations, and model-assisted language.

See how these definitions support a real analysis.

Read the Next.js full analysis