# Documentation Bc Analysis Generator

> Create well-structured Business Central feasibility analysis documents in the `openspec/analysis/` folder as the AL Analyst's working artefact backing a CCN, following the ANALYSIS-001 template structure. Captures references to the source user story / spec / CCN, change summary, scope & impact (objects added/modified, LoC, ID range usage), phased time estimate (Optimistic / Expected / Pessimistic…

- **Type:** Skill
- **Install:** `agentstack add skill-fernandoartalf-al-copilot-skills-collection-documentation-bc-analysis-generator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fernandoartalf](https://agentstack.voostack.com/s/fernandoartalf)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fernandoartalf](https://github.com/fernandoartalf)
- **Source:** https://github.com/fernandoartalf/AL-Copilot-Skills-Collection/tree/main/skills/documentation-bc-analysis-generator
- **Website:** https://alcopilotskills.com/

## Install

```sh
agentstack add skill-fernandoartalf-al-copilot-skills-collection-documentation-bc-analysis-generator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Documentation: BC Analysis Generator

Generate a Business Central feasibility analysis document under `openspec/analysis/` as the AL Analyst's working artefact that supports a change-control note (CCN) and a draft technical spec. The spec describes **what** to build, the architecture explains **why**; this document answers **is it worth building, at what cost, and what is the risk?**.

## When to use

The user has a draft technical spec (and ideally a CCN) and needs a formal feasibility decision — effort, cost, SWOT, risks, GO / NO-GO — before development begins.

## Default output location

`openspec/analysis/` — always. Do not ask the user where to save the file.

## Workflow

Follow these steps in order. Do not skip the spec validation or the GO/NO-GO recommendation step.

### Step 1 — Identify and validate the source spec

1. If the user did not specify a SPEC ID, list files in `openspec/specs/` and ask which one to analyse via `vscode_askQuestions`.
2. Read the chosen spec file and capture: `id` (SPEC-NNN), `title`, `user_story` (US-NNN), `module`, `prefix`, `id_range`, `estimated_effort` (if present), the full AL object inventory (tables, enums, pages, page extensions, codeunits, permission sets), the phase overview, and any Open Questions.
3. Read the linked user story and capture: ACs, Out-of-Scope items, Open Questions resolution status (resolved vs. still open).
4. If a CCN exists for the feature (e.g. `docs/ccn/CCN-NNN-*.md` or referenced from spec frontmatter), read it and capture: `ccn` id, requested change, business justification, approval status.
5. If the spec's Open Questions are not all resolved, warn the user — an analysis on a moving spec produces unreliable estimates. Allow override but record it as Assumption.

### Step 2 — Allocate the next ANALYSIS ID

1. List files in `openspec/analysis/` matching `ANALYSIS-*.analysis.md`.
2. Parse the highest existing numeric ID and increment by 1; format as `ANALYSIS-NNN` (zero-padded to 3 digits).
3. If the folder does not exist or is empty, start at `ANALYSIS-001`.
4. If the allocated filename would collide, re-increment until free. Never overwrite.

### Step 3 — Research the workspace to ground the estimate

Mandatory before drafting the time and cost tables:

1. Re-read `app.json` for `application` version, `runtime`, `name`, `publisher`, and `idRanges` — confirms object-ID availability claimed in the spec.
2. Use the `Explore` subagent (thoroughness `quick` or `medium`) to inventory existing AL objects under `src/` that the new objects depend on, reuse, or coexist with. The reuse vs. greenfield ratio drives the estimate.
3. Count the spec's planned new AL objects (tables, enums, pages, page extensions, codeunits, permission sets) and modified objects. Record both in §3 of the analysis.
4. Sanity-check the spec's phase decomposition — every phase MUST end with green build + green tests; if a phase appears non-shippable, flag as a SWOT Weakness.

### Step 3b — Blind spot & assumption review

After researching the workspace and **before** verifying BC mechanisms or building the estimate, enumerate the tacit assumptions and analytical blind spots you detected in the spec, user story, and codebase. Surface them to the user via `vscode_askQuestions`. For each item, offer three dispositions:
- **Confirm the assumption is valid** — recorded in §5 Assumptions with justification.
- **Assumption is invalid / uncertain** — the relevant phase estimate is escalated to Pessimistic and a Risk entry is added.
- **Out of scope** — recorded in §2 Change summary as explicitly excluded.

Minimum areas to check (raise at least one question per applicable area):

1. **Unresolved Open Questions** — For every Open Question in the user story or spec that is still in status "Escalated" or "Functional question", flag it explicitly. An analysis built on unresolved functional decisions produces unreliable estimates.
2. **Pre-requisite data & configuration** — Does the estimate assume that master data (Resources, Employees, No. Series, catalogue tables) is already configured in the target tenant? If so, is that a valid assumption for go-live?
3. **Test-data availability** — Does the testing strategy require realistic data (e.g. existing penalties, vehicle registrations, driver records)? Who is responsible for providing it, and is the time to create it included in the estimate?
4. **Vague spec language** — Flag any spec section whose scope is ambiguous (e.g. fields described as "TBD", phases with no task breakdown, ACs that use "should" or "might"). These inflate estimation uncertainty; list them as Weaknesses in §6.
5. **Phase shippability gaps** — If a phase produces objects that cannot be independently tested (e.g. a codeunit with no test harness, a table with no page), it is a non-shippable phase. Flag this as a risk.
6. **External dependencies not estimated** — Does any phase depend on input from the customer (data migration files, configuration decisions, third-party API credentials)? Is customer wait-time included in calendar duration?
7. **BC version / platform constraints** — Does the spec use any mechanism whose availability on the target BC `application` version is not yet verified (Step 4)? Treat as Pessimistic until verified.
8. **Scope creep vectors** — Are there any near-in-scope capabilities implied by the spec (e.g. a list page implies the user will want filtering, sorting, export) that are explicitly excluded? Record them as Threats if they are likely to resurface as change requests.

Do not proceed to Step 4 until all raised assumptions have been assigned a disposition.

### Step 4 — Verify standard BC assumptions used in the estimate

For every estimate line that relies on reuse of a standard BC mechanism (RecordRef / FieldRef, EnqueueBackgroundTask, RapidStart configuration packages, No. Series, Permission Sets, virtual tables `AllObj` / `Field`, Document Attachment, etc.):

1. Call `mcp_microsoftdocs_microsoft_docs_search` to confirm the mechanism exists on the BC `application` version from `app.json`.
2. If unverified, raise the corresponding phase's estimate to **Pessimistic** and record an Assumption.
3. If documentation contradicts the spec's reuse claim, downgrade the recommendation toward **CONDITIONAL-GO** and surface a blocking advisory.

### Step 5 — Build the per-phase estimate

1. **Hours table** — one row per phase from the spec's §8 phase overview, with three columns: `Optimistic (h)`, `Expected (h)`, `Pessimistic (h)`. Add a Subtotal row, then a 20 % contingency on Expected, then a Total row.
2. Each phase estimate MUST be defensible against the task list in the spec's `PLAN-NNN-PN-*.plan.md` file (or the spec's §8 if plans don't yet exist). Do not invent tasks.
3. **Calendar duration** — translate Total hours to working days assuming a single AL developer FTE at 7 productive h/day (default), sequential phases. Use rounded `~weeks` for wall-clock.
4. **Rate** — default **EUR 80 / hour**. If the user specifies a different rate or currency, use it and record it in §5 Rate line.
5. **Cost** — multiply Optimistic / Expected / Pessimistic Total hours by the rate. Provide a per-phase cost breakdown for the Expected scenario.
6. **Assumptions** — record at least: developer familiarity, mock-vs-live testing strategy, exclusions (translation / licensing / sandbox), and architect review cycles.

### Step 6 — Build the SWOT analysis

1. Minimum 3 bullets per quadrant: **Strengths**, **Weaknesses**, **Opportunities**, **Threats**.
2. Bullets MUST be specific to the spec — generic statements like "good design" are not acceptable. Reference object IDs, ACs, or design decisions where useful.
3. Strengths typically include: additive-only change, mature reuse, phased shippability, test strategy.
4. Weaknesses typically include: performance edge cases, UI gaps explicitly accepted by the US, length/format limits.
5. Threats MUST include the *cost of NOT implementing* (the do-nothing baseline) — this is a standard Avvale practice.

### Step 7 — Build the numbered risk register

1. Table columns: `# | Risk | Likelihood | Impact | Mitigation`.
2. IDs are `R-01`, `R-02`, … (zero-padded to 2 digits).
3. `Likelihood` and `Impact` MUST each be one of: `Low`, `Medium`, `High`.
4. Every risk MUST have a non-empty `Mitigation` — point to the phase/task or AC that covers it. If a risk has no mitigation, escalate it to a blocking advisory in §8.
5. Add a closing line `**Overall risk rating: **` based on the highest-Likelihood/Impact combination.

### Step 8 — Issue the feasibility recommendation

1. Pick exactly one verdict: **GO** (unconditional), **CONDITIONAL-GO** (with explicit pre-conditions), or **NO-GO**.
2. Justify the verdict in one short paragraph that cites: technical complexity, additive-vs-invasive nature, scope-creep risk, expected cost vs. strategic value.
3. List **Non-blocking advisories at kick-off** as numbered bullets (typical: reserve test tenant, defer migration to separate CCN, grooming items for v2, frontmatter backfills).
4. Never issue `GO` if any High-Impact risk has High-Likelihood without an in-phase mitigation. In that case, downgrade to `CONDITIONAL-GO` and state the pre-condition.

### Step 9 — Build the filename

Format: `ANALYSIS-NNN-.analysis.md`

- `` is the lowercase, hyphen-separated title (diacritics stripped, non-alphanumerics removed, hyphens collapsed). Typically equal to the spec's kebab title.
- Validate against `^ANALYSIS-\d{3}-[a-z0-9]+(-[a-z0-9]+)*\.analysis\.md$` before writing.

### Step 10 — Write the analysis document

Create the file at `openspec/analysis/` using the template in `references/analysis-template.md`. The file MUST contain, in this exact order:

1. YAML frontmatter:
   ```yaml
   ---
   id: ANALYSIS-NNN
   title: Feasibility analysis — 
   version: 1.0.0
   status: draft
   spec: SPEC-NNN
   user_story: US-NNN
   ccn: 
   prepared_by: 
   date: 
   recommendation: 
   related_docs:
     - openspec/specs/SPEC-NNN-.spec.md
     - openspec/userstories/US-NNN-.userstory.md
     # add CCN doc only if it exists
   ---
   ```
2. `# ANALYSIS-NNN — Feasibility analysis for SPEC-NNN` H1.
3. A leading paragraph naming the analysis as the AL Analyst's output backing the CCN, with markdown links to the spec, user story, and CCN.
4. `## 1. References` — table of source artefacts (`Artefact | Path | Status`).
5. `## 2. Change summary` — bullet list of new objects, modified objects, and explicit "zero legacy touched" / migration-deferred statement (echoing the US Out-of-Scope).
6. `## 3. Scope & impact` — single table with columns `Dimension | Value`. Minimum rows: new AL objects, existing objects modified, legacy factboxes/objects modified, BC modules touched, external dependencies added, net new AL LoC estimate, object ID range usage. Close with a one-line Open-Questions resolution status from the source US.
7. `## 4. Time estimate` — leading paragraph (blended rate, contingency note), then the per-phase hours table, then the calendar-duration table.
8. `## 5. Cost estimate` — rate line, cost-per-scenario table, per-phase Expected-scenario cost breakdown, `### Assumptions` subsection.
9. `## 6. SWOT analysis` — `### Strengths`, `### Weaknesses`, `### Opportunities`, `### Threats` subsections (in this exact order).
10. `## 7. Risk assessment` — risk register table and overall risk rating line.
11. `## 8. Feasibility recommendation` — `### **** — ` heading, justification paragraph, `### Non-blocking advisories at kick-off` numbered list. If verdict is `CONDITIONAL-GO`, add `### Pre-conditions` numbered list above the advisories.
12. `## 9. Handoff back to the Architect` — bullet list of the next decision points (typically: accept → set SPEC to `approved`; reject → revise SPEC and re-analyse).

### Step 11 — Optional spec back-link

If, and only if, the source spec does not yet reference this analysis, you MAY append the ANALYSIS file to the spec's frontmatter `related_docs` list (if present) or add a one-line "Analysis: [ANALYSIS-NNN](...)" pointer near §1. Do not change the spec's `status` or any other field.

### Step 12 — Confirm and report

After writing, report to the user:

- Path of the created analysis file (as a markdown link).
- The allocated `ANALYSIS-NNN` id.
- The verdict (`GO` / `CONDITIONAL-GO` / `NO-GO`) and the Expected-scenario cost and duration.
- The number of risks and the overall risk rating.
- Any pre-conditions or non-blocking advisories the user must action.
- The next recommended action (typically: present to Architect for spec approval, or revise the spec on `CONDITIONAL-GO`).

## Heading & full-content translation rules

Every artefact produced by this skill MUST follow these rules. They exist so
the downstream `documentation-bc-md-to-docx-converter` pipeline (AXZ Word
templates) renders correctly in every supported language and so headings
never leak design-time tokens.

1. **No manual H2 numeric prefix.** Write `## Business context`, never
   `## 2. Business context`. The Word template's multilevel-list style
   numbers the H2s automatically; a manual `N. ` prefix produces double
   numbering (e.g. `2. 2. Business context`) in the rendered docx.
2. **No source-ID suffix in any heading.** Drop trailing parentheticals
   such as `(from US-NNN)`, `(from US-)`, `(procedente de SPEC-001)`,
   `(aus ARCH-NNN)`, etc. Trace links to source artefacts belong in the
   frontmatter or section body, not in the visible heading text.
3. **Translate H3 subsection labels.** Subsections keep their `N.M ` prefix
   shape (e.g. `### 3.1 …`) but the label text MUST be translated into the
   target language declared in the frontmatter `language` / `locale` field.
4. **Translate the ENTIRE table.** When a target language is set, every
   column header AND every cell value in every table MUST be in that
   language. No English fallbacks for cells, no mixed-language rows. Code
   identifiers (object names, field names, AL keywords) stay verbatim;
   surrounding prose translates.
5. **Regression guard.** Before saving, scan the artefact for these
   anti-patterns and fix them:
   - `^## \d+(?:\.\d+)*\.\s` (numeric-prefixed H2)
   - `\((?:from|procedente de|issu[e]? de|aus|da|de|uit)\s+[A-Z]+-\S+\)\s*$`
     on any heading line (source-ID suffix)
   - English column headers when the document is non-English.

> Origin: defects discovered while producing `CCN-001-driver-penalty-management`.
> Tracked in `docs/plans/PLAN-documentation-bc-heading-translation-fix.md` (PLAN-DOC-BC-003).

## Hard rules

- **status MUST always be `draft`** on initial creation. **version MUST be `1.0.0`**.
- **The `prepared_by` frontmatter field is mandatory.** It must contain the full name of the human user — never an agent role or agent name. If the author name is not evident from context (git user, previous artefacts, or explicit user input), ask the user before writing the file.
- **Default folder is `openspec/analysis/`** — never ask, never write elsewhere.
- **File extension MUST be `.analysis.md`**.
- **Never** create an analysis file without a referenced spec — the `spec:` frontmatter field is mandatory.
- **Never** invent risks, costs, or hours — every estimate MUST be derivable from the spec's phases or the linked plan files.
- **Never** assert standard BC reuse without Microsoft Learn verification (Step 4). Unverified assumptions push the phase estimate to Pessimistic.
- **Never** overwrite an existing analysis file. On collision, re-allocate the ANALYSIS ID.
- **Never** issue `GO` when a High-Impact + High-Likelihood risk lacks an in-phase mitigation — downgrade to `CONDITIONAL-GO`.
- Every SWOT quadrant MUST have at least 3 bullets, all specific to the spec.
- Every risk in §7 MUST have a non-empty Mitigation.
- The analysis document MUST NOT contain AL source code. Estimates, tables, and prose only.
- The `recommendation:` frontmatter field MUST match the verdict heading in §8 exactly.
- **Never** skip Step 3b —

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fernandoartalf](https://github.com/fernandoartalf)
- **Source:** [fernandoartalf/AL-Copilot-Skills-Collection](https://github.com/fernandoartalf/AL-Copilot-Skills-Collection)
- **License:** MIT
- **Homepage:** https://alcopilotskills.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fernandoartalf-al-copilot-skills-collection-documentation-bc-analysis-generator
- Seller: https://agentstack.voostack.com/s/fernandoartalf
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.