SC4SAP Program → Specification

Reads an existing ABAP program (Report / Module Pool / FM Group / Class / CDS / RAP) via MCP, runs structural + semantic + where-used analysis, then produces a Specification artifact in any combination of Markdown (.md), HTML (.html, one self-contained file) and Excel (.xlsx). Scope is negotiated Socratically — start wide, narrow on each turn, stop when the user's target granularity is confirmed.

<Response_Prefix>Every response triggered by this skill MUST begin with [Model: <main-model> · Dispatched: <sub-summary>] per ../../common/model-routing-rule.md § Response Prefix Convention.</Response_Prefix> <Target_Object>The target object is looked up on the active profile's system only. Not found → stop and ask per ../../common/multi-profile-artifact-resolution.md § Target object not on the active system — never substitute a similar name, never switch profiles on your own.</Target_Object>

<Phase_Banner>Multi-phase skill. Before each Agent(...) dispatch, emit ▶ phase=<id> (<label>) · agent=<name> · model=<Opus 4.7|Sonnet 4.6|Haiku 4.5> per ../../common/model-routing-rule.md § Phase Banner Convention. Resolve the dispatch mode first per ../../common/model-dispatch-mode.md: auto (default) uses the model below/in the rule; user-defined asks the user Opus / Sonnet / Haiku (recommended one first) before each dispatch group.</Phase_Banner>

<Team_Mode>No teamMode integration. program-to-spec targets a single object (one program / class / FM group / CDS / RAP BO) and performs read-only structural extraction — no cross-module synthesis, no authoring conflict, no incident triage. See ../../docs/team-consultation-architecture.md § 6 gating logic. Future extension: if a target's GetWhereUsed graph spans ≥ 2 modules AND user picks L4 depth, Type A (module consultants annotating cross-module concerns in Step 3) could be added — not in current scope.</Team_Mode>

<Use_When>

• User says "program to spec", "reverse engineer", "make a spec", "document this program", "functional specification", "technical specification", "generate a specification"
• Knowledge transfer / handover of legacy ABAP to another team
• Preparing a refactoring or rewrite (need to capture as-is behavior)
• Compliance / audit requires a written spec for custom code
• Building a WRICEF inventory with detailed per-object specs </Use_When>

<Do_Not_Use_When>

• User wants a code quality review → /sc4sap:analyze-code
• User wants to create a new program from a spec → /sc4sap:create-program
• User wants to fix the program → direct MCP Update* calls or re-run /sc4sap:create-program
• Object does not exist yet </Do_Not_Use_When>

<Session_Trust_Bootstrap> MANDATORY — runs as Step 0a before any MCP call or user interaction.

Invoke /sc4sap:trust-session with parent_skill=sc4sap:program-to-spec to pre-grant MCP tool + file-op permissions (eliminates per-tool prompts during structural reads + screen rendering pipeline).

• If .sc4sap/session-trust.log already has a line within the last 24h, skip silently.
• Otherwise run it and surface the one-line confirmation.

Full spec: see ../trust-session/SKILL.md. </Session_Trust_Bootstrap>

<Socratic_Scope_Narrowing> The interview is a funnel: every turn reduces the remaining decision space. Score remaining ambiguity 0–10 after each answer; stop when ≤3.

Default opener — bundled 4-question AskUserQuestion (MANDATORY when the target object is already supplied in ARGUMENTS): Issue ONE AskUserQuestion call with these four questions in this exact order — Audience / Format / Depth / Language — each with "(Recommended)" as the first option. Format is multi-select (multiSelect: true); the other three are single-select. This replaces Rounds 2+3+5 in one UI turn. Only fall back to per-round questioning when the object itself is missing or ambiguous (Round 1) or when the user picks L3/L4 (Round 4 scope trimming).

Round 1 — Target object (only if ARGUMENTS did not supply it)

• "Which object? (program / FM group / class / CDS / RAP BO name)"
• Verify via SearchObject. If ambiguous, list candidates.

Round 2 — Audience + format (covered by the default opener — do not ask separately)

• Audience: Functional (business readers — SD/FI/MM users) vs Technical (developers) vs Both
• Format (any combination): Markdown (review-friendly, git-friendly) · HTML (one self-contained file with images inlined — share, mail, print) · Excel (project-PMO-friendly, reviewable cell-by-cell)
• Default if user says "up to you" / "you choose" → Audience Both + Format Markdown.

Round 3 — Depth (pick one) (covered by the default opener)

Round 4 — Scope trimming (only if L3/L4) Ask ONE narrowing question per turn until ambiguity ≤3:

• "Include unit tests inventory?"
• "Include generated artifacts (Screens / GUI Status / Text Elements)?"
• "Cover all includes or just main?"

Where-Used scope (L4 only — fixed default, no interactive prompt)

• Target = main program / class / FM-group / CDS / RAP-BO object + each of its screens (T1+Screen).
• Caller filter = customer namespace Z* / Y* only (S2). Standard SAP and add-on namespaces are excluded.
• The rendered Where-Used section MUST repeat this scope in its header so reviewers know what was (and wasn't) searched.

Round 5 — Output location

• Default: .sc4sap/specs/{object_name}-v{ver}-{lang}.{md|html} (versioned, history in {object_name}-{lang}.history.json — see edit-mode.md) and .sc4sap/specs/{object_name}-{YYYYMMDD}-{lang}.xlsx — one file per selected format, plus the same files with -en (English companion, workflow-steps.md Step 6) when lang ≠ en
• Language: ko / en / ja (infer from user's current language; confirm once).

Stop condition: every dimension above has a concrete answer OR user explicitly says "skip remaining, use defaults". </Socratic_Scope_Narrowing>

<Workflow_Steps> The 7-step workflow (Step 0 Socratic → Step 5 Review → Step 6 English companion) lives in a companion file to keep this skill doc short.

MUST read workflow-steps.md (in this skill folder) and execute the steps defined there in order whenever this skill runs. </Workflow_Steps>

<Spec_Templates> The Markdown L2 skeleton and the Excel sheet-naming convention live in a companion file.

MUST read spec-templates.md (in this skill folder) when rendering the artifact in Step 4. </Spec_Templates>

<Agent_Composition> Per-step model allocation. The main thread follows the session model (model: inherit); each Agent(...) carries its own model (frontmatter or explicit override).

• Main orchestrator (Sonnet 4.6) — Steps 0, 1, 1.5, 2, 5: Socratic interview orchestration, object classification routing, CBO context preload, Step 5 review loop. State tracking across depth / format / language dimensions needs Sonnet headroom.
• Analysis (sap-analyst × 1, Opus 4.7, frontmatter) — Step 3 primary dispatch: extracts business purpose, inputs, outputs, data sources (including CBO-annotated Z-references when cbo-context.md exists), main-logic narrative, authorization checks, error cases. One dispatch covers all narrative dimensions to keep context continuous.
• Rendering (sap-writer × 1) — Step 3 second dispatch (or Step 4 render invocation):
  • L1 / L2 depth → Haiku 4.5 base (frontmatter). Pure templating from structured analyst output.
  • L3 / L4 depth → Sonnet 4.6 override (model: "sonnet") — longer narrative + deeper cross-reference + stronger consistency requirement.
  • Markdown / HTML output — writer renders the .md; HTML is produced from that same .md by scripts/spec/md-to-html.mjs (no second writer pass).
  • Excel output — writer's deliverable is TWO JSON files consumed by scripts/spec/build-spec.mjs:
    1. TR (translation) map — English source string → target-language replacement mapping; schema + slot semantics in spec-templates.md § Excel — Template-clone.
    2. image-spec.json — {selection, alv, processFlow, lang} per-program image data; exact key names + sample values in spec-templates.md § Image Replacement, and selection MUST follow selection-schema.md (blocks / pushbuttons / radio groups transcribed 1:1 from source). Drives the Sheet 3 Selection/ALV mockups + Sheet 4 horizontal Process Flow PNG. Writer does NOT generate workbook styles, drivers, geometry, or PNGs directly — asset/template_base.xlsx supplies geometry, build-spec.mjs does clone + render + swap in one shot. Depth-driven model override still applies (Sonnet for L3/L4 because the warning-row and processing-step narrative is longer). Two hard requirements on both JSON files (full rules in spec-templates.md): (1) business-first content — Sheet 4 Step text + processFlow[] describe the business process for a functional reader, with the ABAP event/FORM kept as a secondary annotation (never an event-only list); (2) single-language output — every prose string is in the target lang; only SAP identifiers / ABAP literals stay as-is. build-spec.mjs prints a ⚠ LANGUAGE MIX gate for ko/ja — finalize only when it reports language check OK.
• English companion (sap-writer × 1, model: "sonnet" override) — Step 6, when lang ≠ en: translates the finished files (.md, image-spec.json, tr.json) into their -en twins; the main thread re-runs the same render scripts on them.
• Audit verification (sap-critic × 1, Opus 4.7, frontmatter, conditional L4 only) — Step 3 gate: verifies every claim in the rendered spec cross-references a concrete line range in source. Skip for L1 / L2 / L3.

</Agent_Composition>

<Output_Format>

Spec generated: ZSDR_OPEN_ORDER_ALV  v1.0
Depth: L2 Standard · Format: markdown, html · Lang: ko
Sections: 9 · Tables referenced: 6 · Screens: 1 · GUI status: 1
Files: .sc4sap/specs/ZSDR_OPEN_ORDER_ALV-v1.0-ko.md
       .sc4sap/specs/ZSDR_OPEN_ORDER_ALV-v1.0-ko.html      (editable: Edit → Save → …-edited.html)
       .sc4sap/specs/ZSDR_OPEN_ORDER_ALV-ko.history.json
       .sc4sap/specs/ZSDR_OPEN_ORDER_ALV-v1.0-en.md        (English companion)
       .sc4sap/specs/ZSDR_OPEN_ORDER_ALV-v1.0-en.html
       .sc4sap/specs/ZSDR_OPEN_ORDER_ALV-en.history.json
Edited copy back from a reader? Hand over the …-edited.html — it is imported as v1.1 (edit-mode.md § Import).

Top-level summary:
  Report that lists open sales orders by Sales Organization and date range and displays them via ALV.
  Main tables: VBAK, VBAP, VBUK, KNA1 (+ CDS I_SalesOrder).
  Authorizations: S_TCODE=ZSDR01, S_TABU_DIS=VBAK.

Next options:
  • "Regenerate as Excel" / "Also give me HTML"
  • "Extend to L4 with Where-used"
  • "Japanese version too"

</Output_Format>

<MCP_Tools_Used>

• SearchObject, GetObjectInfo
• GetProgFullCode, GetIncludesList, GetInclude
• ReadClass, ReadFunctionModule, ReadInterface, ReadView
• Read BehaviorDefinition, Read BehaviorImplementation, Read ServiceDefinition, Read ServiceBinding
• GetLocalDefinitions, GetLocalMacros, GetLocalTestClass, GetLocalTypes
• GetScreensList, GetGuiStatusList, GetGuiStatus, GetTextElement (language: "E")
• GetSqlQuery — T100 message texts only, BASIS ≥ 7.50 (see Data_Extraction_Safety)
• GetMetadataExtension
• GetAbapAST, GetAbapSemanticAnalysis
• GetWhereUsed, GetEnhancements, GetEnhancementSpot </MCP_Tools_Used>

<Related_Skills>

• /sc4sap:analyze-code — code quality review (what's wrong)
• /sc4sap:create-program — spec → new program (forward direction)
• /sc4sap:deep-interview — requirement clarification for new builds </Related_Skills>

<Data_Extraction_Safety> Spec generation only reads source code + DDIC metadata + where-used — never GetTableContents / GetSqlQuery. No row data is extracted. One exception: GetSqlQuery on T100 (message texts — repository text, not business data) with the explicit fields ARBGB, MSGNR, TEXT, filtered to SPRSL = 'E' and the message classes / numbers the source actually uses, so the spec can print CODE (English text) (workflow-steps.md § Message references). The normal approval prompt still applies. On BASIS < 7.50 GetSqlQuery is unavailable; fall back to the source text as that section describes — never GetTableContents on T100. The blocklist hook is respected if the user asks for sample data (refuse and document the request in the Risk sheet instead). </Data_Extraction_Safety>

<Inputs_And_Screens_Rendering> xlsx output — always-on pipeline (clone + program-specific imagery): every xlsx spec runs scripts/spec/build-spec.mjs <tr.json> <image-spec.json> <out.xlsx>. The helper clones asset/template_base.xlsx (geometry / styles / fonts / column widths / row heights / image anchors — all preserved), renders three program-specific PNGs from image-spec.json, then swaps them into the cloned xlsx with dynamic <xdr:ext> extents (no stretching). Three image slots are populated on every spec:

• Sheet 3 Selection (xl/media/image2.png at C4) — driven by image-spec.json.selection
• Sheet 3 ALV (xl/media/image1.png at C19) — driven by image-spec.json.alv
• Sheet 4 Process Flow (xl/media/image3.png at B19, horizontal layout) — driven by image-spec.json.processFlow (each program has a different flow, so drawing4.xml is injected on demand from a blank template container)

Graceful degrade: if no headless browser is on PATH, renderScreenImages returns null per slot and build-spec.mjs keeps the template mockups for that slot — never crashes.

No trigger keywords required. Image rendering is part of the default Excel pipeline because each program has unique selection screens, ALV layouts, and flow charts. Drift risk applies only to geometry regression (the old throwaway-driver problem) and image swap only touches drawing extents + PNG bytes, not geometry.

Markdown output — unchanged: continue emitting ASCII wireframes inside fenced code blocks (Step 3.5 in workflow-steps.md). ASCII wireframes never go in xlsx cells.

HTML output: converted from the finished .md by node scripts/spec/md-to-html.mjs <spec.md> --editable --version <ver> — PNGs inlined as data URIs, Mermaid fallbacks drawn by the Mermaid CDN script when opened online (plain source text offline). Same content as the .md, by construction, laid out as a web page: contents sidebar, cover fact card with the version, cross-linked SAP names, sortable / filterable tables, callouts, a Functional view, and a Revision History section. The writer follows html-markup.md so the page can find what it needs.

Edit mode and versions: the page has an Edit button — readers change text, table rows, list items, images and flows in place and Save an …-edited.html carrying their revision (+0.1, author, note). md-to-html.mjs --import turns it back into the next version's .md (only the edited blocks change) and records the revision in history.json. Versioning, review-loop rebuilds (--same-version), import and the English companion: MUST read edit-mode.md before building or importing an HTML spec. </Inputs_And_Screens_Rendering>

Task: $ARGUMENTS