Capability Overview

Quick Start

Write capability overview documents under the consuming repository's root capabilities/<slug>/ folder using the preset template in templates/capability-overview-template.md.

Before creating any output files or running the helper script, run a grill-me style clarification session using ../grill-me/SKILL.md. Ask one question at a time until the capability name, domain, objective, scope, stakeholders, systems, terminology, assumptions, constraints, and desired output are clear enough to avoid avoidable misunderstanding.

During that clarification session, use ../ubiquitous-language/SKILL.md whenever terms are vague, overloaded, conflicting, or important enough to become shared domain language. Create or update <private-lab-root>/GLOSSARY.md inline as terms are clarified; do not batch glossary updates until the end. Do not write the glossary inside this public toolkit repository when working with real company context.

After the clarification session, validate that <private-lab-root>/GLOSSARY.md was created or updated during the current run. If it was not created or updated, stop before generating capability overview files and ask the user to run the grill-me skill followed by the ubiquitous-language skill so the glossary is updated first.

When this toolkit is used as a submodule, do not write generated capability files under toolkit/capabilities/. Run the command from the private repository root, or pass --output-root <private-repo-root>, so output goes to <private-repo-root>/capabilities/.

Use the helper script only after the clarification session and glossary validation are complete, and only when the requested capability has clear input values:

python3 skills/capability-overview/scripts/write-capability-overview.py "Order Management" \
  --domain "Commerce" \
  --business-objective "Improve order accuracy, lifecycle visibility, and fulfillment coordination." \
  --stakeholder "Customer service" \
  --stakeholder "Operations" \
  --existing-system "ERP" \
  --strategic-importance "High" \
  --pain-point "Order status is fragmented across systems." \
  --related-capability "Inventory Management"

This creates capabilities/order-management/order-management.md.

If the requested name includes a redundant leading or trailing word Capability, remove it from the generated folder and filename. For example, Search Capability and Capability Search both create capabilities/search/search.md.

Each generated capability must also be added to capabilities/_capability-list.md using a markdown table with name, description, and last_updated columns. Create _capability-list.md when it does not exist. Keep rows sorted alphabetically by capability name.

When running from a private lab repo that contains this toolkit as a submodule:

python3 toolkit/skills/capability-overview/scripts/write-capability-overview.py "Order Management" \
  --domain "Commerce" \
  --business-objective "Improve order accuracy, lifecycle visibility, and fulfillment coordination." \
  --stakeholder "Customer service" \
  --existing-system "ERP" \
  --strategic-importance "High" \
  --pain-point "Order status is fragmented across systems." \
  --related-capability "Inventory Management"

Run from the private lab root, this creates capabilities/order-management/order-management.md beside toolkit/.

Required Inputs

• Capability name
• Domain
• Business objective
• Stakeholders
• Application
• Application lifecycle status
• Owners
• Strategic importance
• Pain points
• Related capabilities

Workflow

1. Start with the grill-me clarification session and update <private-lab-root>/GLOSSARY.md with ubiquitous-language as terminology is clarified.
2. Validate that <private-lab-root>/GLOSSARY.md was created or updated. If not, stop and ask the user to run grill-me and then ubiquitous-language before continuing.
3. Convert the capability name to <workspace-root>/capabilities/<slug>/<slug>.md, removing a redundant leading or trailing word Capability from the slug.
4. Derive the outputs from the inputs and any available repository context.
5. Use templates/capability-overview-template.md as the output structure. Preserve the two opening tables: the document metadata table first, followed by the Data Architecture Overview table, including its capability-specific Relevant ADRs field.
6. Create capabilities/<slug>/diagrams/, then use ../create-drawio-diagram/SKILL.md and its capability context helper to create diagrams/<capability-slug>-capability-overview.drawio. Keep diagram layout, styling, SVG generation, and application-header rules in the create-drawio-diagram skill.
7. Export or create diagrams/<capability-slug>-capability-overview.svg, sanitize it according to the Draw.io SVG export rules, and embed it in the capability overview just above Main Business Features without a separate diagram heading.
8. Do not overwrite an existing capability file unless the user explicitly asks.
9. Add or update the generated capability in <workspace-root>/capabilities/_capability-list.md with a relative link to <slug>/<slug>.md, description, and last_updated date.
10. Populate the Relevant ADRs field in the capability's Data Architecture Overview table with links to confirmed ADRs that directly affect the capability. Use each ADR title as its Markdown link label and separate multiple links with <br>. Leave the field empty when none are confirmed; do not add an empty-state message or invent ADR paths.
11. If the toolkit is mounted as toolkit/ in a private lab repo, write the generated capability overview to the private lab root, not to toolkit/capabilities/.
12. Keep company-confidential details out of the public toolkit repository; use a private company lab repo for real company content.
13. Run the readability and glossary compliance gate before finishing:

• Read <private-lab-root>/GLOSSARY.md.
• In the Glossary, find the Jargon section and its Avoid list.
• Search the generated capability overview Markdown for each avoided word or phrase.
• Replace avoided wording with the preferred glossary term when one is available.
• If no preferred term is available, rewrite the sentence in plain language or add an open question rather than leaving the avoided wording in the overview.
• Repeat the search after edits until no avoided terms remain, except inside explicit glossary references or quoted source text.
• Reread the opening sections and simplify any sentence that a non-technical business reader would need to parse twice.

Required Outputs

Each capability overview must include:

• Document metadata table
• Data Architecture Overview table with the capability name, description, domain, application, application lifecycle status, owners, and relevant ADR links
• Capability definition
• Short Summary in italic text above Business Objective
• Business outcome
• Capability context diagram as editable .drawio and embedded .svg, both stored under diagrams/
• Main Business Features
• Scope
• Inputs/outputs
• Processes supported
• Applications involved
• Application lifecycle management
• Data involved
• Integrations
• Potential KPIs
• NFR considerations
• Risks
• Maturity assessment
• Future-state considerations

Readability Guidance

Capability overviews are for non-technical business readers. Architects and delivery teams should get enough context to act, but the document must be understandable to a reader without technical training and must start from business outcomes, ownership, impact, trade-offs, risks, and open questions.

Use the check-readability skill in ../check-readability/SKILL.md before finishing a capability overview. Treat the target audience as non-technical business stakeholders unless the user gives a different audience. Aim for a Flesch Reading Ease score of 40 or higher; revise the generated overview before finishing if the score is below 40.

The capability overview is not complete until the readability check passes these capability-specific expectations:

• Flesch Reading Ease is 40 or higher, or any lower score is explicitly justified because required names, legal terms, or quoted source text make the target impractical.
• The opening sections put the business outcome, operational impact, scope, trade-offs, risks, and open questions before implementation detail.
• Glossary Jargon terms from Glossary.md or GLOSSARY.md are removed from generated prose, headings, tables, and diagram labels unless they are quoted source text or explicit glossary references.
• Preferred glossary terms are used exactly when the glossary gives one. If a preferred term is missing or unclear, use plain language and capture the terminology gap as an open question.
• Acronyms are spelled out the first time they appear unless the expanded form would be misleading or the term is already defined in the glossary.
• Vague architecture filler such as "robust", "seamless", "future-proof", "best practice", or "enterprise-grade" is removed unless tied to a concrete requirement, KPI, risk, cost, owner, or decision.
• Long table cells are moved into notes or the relevant section when they make ownership, scope, risks, KPIs, or decisions hard to scan.
• Open questions are written as answerable questions with an owner or target audience when known.

Template

Use templates/capability-overview-template.md as the source template for generated capability overview files.