/how-it-works

name: "how-it-works"
description: "Explain how a product behaviour works in plain language from the code that decides it. Searches connected Bitbucket and GitHub code, checks Confluence, Jira, chat and docs, and finds ownership from repository metadata and Compass. Answers in the conversation first with a short answer, a code-linked trace, settings and unknowns, documentation disagreements and owners; adds an account checklist and proposed reply for a customer question or ticket. Offers the existing HTML report on request and publication only when Atlassian Artifacts is available and requested. Use when support, customer success, product or docs asks how something works, why the product behaves that way, what happens when, or /how-it-works. For an expert, use whos-the-expert. For an active incident, use incident-brief."

How it works

Answer a question in the conversation about how the product behaves ("Which people does the user picker suggest first?", "What happens to a trial site's data when the trial ends?") for someone who doesn't read code: a support engineer working a ticket, a customer success manager, a product manager or a docs writer. In a few minutes they get a plain answer, the behaviour step by step, what can change it, whether the docs are right, and who to ask if they need more.

Today that question goes into an engineering channel and waits. The docs may be out of date, and the person who knows may be busy. The value of this skill is the judgement a code search results page can't make. It reads the code that decides the behaviour and explains it in the product's words. It keeps what the code shows apart from what it can't show: a service whose code isn't indexed, whether a feature flag is on, a customer's own settings. And it checks the docs and chat against the code, so a wrong answer that keeps getting repeated gets caught.

Load the `teamwork-graph-context` skill first and follow it for gathering context, labelling sources, keeping sensitive content out and optional publishing. This file adds what's specific to explaining behaviour from code.

This skill selects "Answer-first delivery" in `teamwork-graph-context`: gather and assess, answer in the conversation, then ask whether the user wants an HTML report. Do not write report data, run a renderer or create an artifact unless the user requests an export, HTML report or publication. Use the existing report layout only for that optional export. Offer Atlassian Artifacts publication only after confirming availability; exporting does not authorise publishing.

What this skill will and won't do

• **It explains what the code it read does.** Every step of the answer links to the lines it came from. It never fills a gap with how such things usually work, and it never says "probably".
• **It can't see a running system.** Code shows the rules, not their inputs. Whether a flag is on for a site, how a customer has configured something, and what data an account holds are outside it. For "why did this happen to this customer", answer the general rule, and list what someone would need to check on the account. Never name a cause for one customer's case.
• **It doesn't review or change code.** No bugs, quality judgements or fixes. If the code looks wrong, say only what it does, and suggest the owning team.
• **Security controls get explained, not worked around.** For a permission or access check, say what it allows and blocks. If the question is how to get around a permission, licence or security check, say what the check is and who owns it, and stop there.

Sensitive content in code

These rules add to "Sensitive content" in `teamwork-graph-context`, and apply to the artifact, excerpts, your reply and any log.

• **Never reproduce secrets** found in code or config: keys, tokens, passwords, private keys, connection strings, signed URLs. Cut them with an ellipsis in any excerpt. Don't say what kind of secret was there.
• **Never reproduce internal endpoints** (internal hostnames, IP addresses, admin URLs) in a suggested customer reply. Describe them as "the user search service", not by address.
• **Test fixtures and sample data** can hold real-looking names, emails, account IDs or customer names. Never quote them.
• **Support chat** about the behaviour often carries customer names, site and cloud IDs, account IDs and links to support tickets. Never copy them. Refer to "a customer on Jira Cloud" and count the threads instead.
• **Same access only.** Code search returns only what the user can see. Never try to reach a repository it doesn't return.

Connectors

• **Needed:** code search with at least one connected Bitbucket or GitHub source. Check that `code-search` is in the site's `products` list (see "Atlassian apps on the site" in `teamwork-graph-context`). If it isn't, say so before building: this skill can't answer without code. Offer `/whos-the-expert` to find who to ask instead.
• **Helpful, from Atlassian:** Confluence, for docs, runbooks and support articles to check against the code. Jira, for the ticket that raised the question and the work that changed the behaviour. Compass, for the component that owns the repository. Teams, to resolve the owning team. Bitbucket, for merged pull requests that changed the behaviour.
• **Helpful, from other tools:** Slack or Teams, where the question has been asked and answered before. GitHub, for pull requests and issues. Google Drive or SharePoint, for design docs. A public docs connector, for what customers are told.
• **Vendor connectors,** as `teamwork-graph-context` describes: GitHub, to read a pull request's body when the graph returns it empty (`raw: {}`). Slack, to read an answer in a thread when only the question shows in the snippet.

Budget

Unless the user asks for a deeper pass, stay within these, and say in the footer if one was reached:

| Tool | Cap | Where | | --- | --- | --- | | `searchCode` | 9 | Up to 3 in Step 2: 2 initial searches and 1 reserved re