solution-documentation

Solution Documentation Generator

Overview

This skill generates structured solution documentation in a consistent, engineering-ready format used for sprint planning, feature specs, and technical handoffs. Each section follows a numbered format with Objective and Action sub-sections, along with relevant technical details (endpoints, DB changes, jobs, flags, etc.).

---

Document Structure

A solution document consists of:

1. A title or context header (e.g., "Solution Approach")
2. Numbered sections, each representing one feature, change, or concern
3. Each section contains:
   • A bold section title (e.g., ### **1. Modification of the Drug Index Table**)
   • * **Objective**: One-sentence goal statement
   • * **Action**: Detailed steps, sub-bullets, DB changes, job names, endpoints
4. API endpoints formatted inline using bold + code style:
   • * endpoint => GET: _**api/Resource/Method?param=value**_
5. Database changes described as column additions, flag changes, foreign key references
6. Background Jobs referenced by name when applicable
7. Flags / Booleans described with their behavior implications

---

Prompt Template for Generation

When the user provides raw requirements (as bullet points, meeting notes, Jira tickets, or conversation), use the following prompt strategy:

You are a senior software architect. Convert the following requirements into a structured Solution Documentation.

FORMAT RULES:
- Number each section starting from 1
- Use markdown bold for section titles: ### **N. Section Title**
- Each section MUST have:
    * **Objective**: [single-sentence goal]
    * **Action**: [detailed implementation steps as sub-bullets]
- For API changes, list endpoints using this format:
    * endpoint => METHOD: _**api/Controller/Action?param=value**_
- For DB changes, describe: table name, column name, type, constraint (FK/index)
- For jobs, reference the exact job class name
- For flags, describe what true/false means in behavior
- Keep language technical but concise
- Do NOT add sections not implied by the requirements
- Maintain YAGNI — only document what is needed

INPUT:
[paste raw requirements here]

---

Section Templates

Standard Feature Section

### **N. [Short Descriptive Title]**

*   **Objective**: [One sentence describing the goal of this change.]
*   **Action**: [High-level description of what needs to be done.]
    *   [Sub-step or detail]
    *   [Sub-step or detail]
    *   endpoint => GET: _**api/Controller/Method?param=value**_
    *   endpoint => POST: _**api/Controller/Method**_

Database Changes Summary Table Section

This section MUST appear at the beginning of any solution document that involves database changes, before the detailed sections. It provides a quick at-a-glance overview of all schema changes across all affected tables.

Status Legend:

• ? New table
• ✏️ Modified table (columns added or altered)
• ?️ Deprecated column (to be removed in a future release)

### **N. DB New Tables & Schema Changes**

| **Table** | **Status** | **Changes / New Columns** |
|---|---|---|
| `TableName` | ? New | `Id` (int, PK), `ForeignKeyId` (int, FK → ReferencedTable), `ColumnName` (nvarchar, Nullable), `Amount` (decimal), `IsDeleted` (bit), `CreatedOn` (datetime) |
| `AnotherTable` | ✏️ Modified | Add `NewColumnName` (int, FK → OtherTable), Add `Flag` (bit, default: 0) |

Rules for this section:

• List every table affected across the entire solution in one consolidated table
• Always specify: column name, data type, PK/FK/Nullable/default constraints
• For FK columns, always reference the target table using FK → TargetTable
• For soft-delete patterns, always include: IsDeleted (bit), DeletedBy, DeletedOn
• For audit columns, always include: CreatedBy, CreatedOn, UpdatedBy, UpdatedOn
• This section is always followed by a Schema Diagram sub-section (N.1)

Schema Diagram Section

This sub-section MUST immediately follow the DB Changes Summary Table. It renders a Mermaid ERD that visualizes the relationships between all new and modified tables.

### **N.1 Schema Diagram**

```mermaid
erDiagram
    ParentTable {
        int Id PK
        string Name
        datetime CreatedOn
    }
    ChildTable {
        int Id PK
        int ParentTableId FK
        string Name
        bit IsDeleted
        datetime CreatedOn
    }
    AttachmentTable {
        int Id PK
        int ChildTableId FK
        string FileName
        string FileUrl
        bigint FileSize
        string FileType
        datetime UploadedOn
    }

    ParentTable ||--o{ ChildTable : "has many"
    ChildTable ||--o{ AttachmentTable : "has attachments"

**Rules for the ERD:**
- Include ALL tables listed in the DB Changes Summary Table
- Show only columns that are relevant to understanding structure and relationships (PK, FK, key business columns)
- Use standard Mermaid ERD cardinality notation:
  - `||--o{` → one-to-many
  - `||--||` → one-to-one
  - `}o--o{` → many-to-many
- Label each relationship with a meaningful verb phrase (e.g., `"has attachments"`, `"categorizes"`, `"typed by"`)
- Do NOT include every audit column in the diagram — keep it readable

### Database Change Section

```markdown
### **N. Modification of [Table/Entity Name]**

*   **Objective**: [Why this DB change is needed.]
*   **Action**:
    *   Add column `ColumnName` of type `DataType` to table `TableName`
    *   This column will be a foreign key referencing `ReferencedTable(Id)`
    *   Flag all existing records: set `ColumnName = [defaultValue]`
    *   New records should be set to `[newValue]`

Background Job Section

### **N. [Job Feature Title]**

*   **Objective**: [What the job does and why it needs updating.]
*   **Action**:
    *   Update job: _**JobClassName**_
    *   Include fields: `FieldOne`, `FieldTwo` in generated output
    *   Apply condition: only for [CountryId / DoctorType / Flag condition]

API Modification Section

### **N. Modification of [API Name]**

*   **Objective**: [What the API change achieves.]
*   **Action**:
    *   Modify search/filter/response logic as described
    *   Extract [data point] from [token / request / DB]
    *   endpoints to be updated:
        *   GET: _**api/Controller/Action?param=value**_
        *   POST: _**api/Controller/Action**_

Conditional Logic Section

### **N. [Feature] for [Country/Role/Condition]**

*   **Objective**: Apply [behavior] only when [condition is met].
*   **Action**:
    *   Add condition check: if `[field] == [value]`
    *   When true: [behavior A]
    *   When false / default: [behavior B]
    *   Affected endpoints:
        *   GET: _**api/Controller/Method**_

---

Formatting Rules

Element	Format
Section header	### **N. Title**
Objective	* **Objective**: ...
Action	* **Action**: ...
Sub-bullets	* detail
API endpoint	GET/POST/PUT: _**api/Path?param**_
Job class name	_**JobClassName**_
DB column	backtick inline code: `ColumnName`
Flag/Boolean	describe both true and false behavior
Country-specific	always mention country name and ID context
DB status icon	? New / ✏️ Modified / ?️ Deprecated
FK reference	`ColumnName` (int, FK → TargetTable)
ERD cardinality	||--o{ one-to-many, ||--|| one-to-one

---

Completeness Checklist

Before finalizing the document, verify each section has:

• [ ] A clear Objective (one sentence, starts with a verb)
• [ ] A detailed Action with at least one concrete sub-step
• [ ] All affected API endpoints listed with HTTP method
• [ ] All DB schema changes described (table, column, type, constraint)
• [ ] DB Changes Summary Table present if any table is added or modified
• [ ] Schema Diagram (Mermaid ERD) present immediately after the DB summary table
• [ ] All FK relationships visualized in the ERD with labeled relationship verbs
• [ ] Any background jobs named explicitly
• [ ] Conditional logic (per country, per role, per flag) noted clearly
• [ ] No duplicate sections — merge related items into one
• [ ] No future/speculative features — follow YAGNI

---

Quality Rules

• One objective per section — if two goals exist, split into two sections
• Endpoints must include HTTP method (GET, POST, PUT, DELETE)
• DB changes must include: table name, column name, data type, and constraint type
• DB Changes Summary Table must consolidate ALL table changes across the document in one place — do not scatter DB changes only in individual sections
• Schema Diagram is mandatory whenever a DB Changes Summary Table is present — never omit it
• ERD must reflect the summary table — every table in the summary must appear in the ERD
• Country-specific logic must always reference the country ID, not just the name
• Job modifications must reference the exact class/job name as it exists in code
• Avoid vague language like "update the system" — be specific about what changes

---

Example Output Excerpt

### **1. DB New Tables & Schema Changes**

| **Table** | **Status** | **Changes / New Columns** |
|---|---|---|
| `SiteExpenses` | ? New | `Id` (int, PK), `SiteId` (int, FK → Sites), `ExpenseCategoryId` (int, FK → ExpenseCategories), `ExpenseTypeId` (int, FK → ExpenseTypes), `Name` (nvarchar), `Amount` (decimal), `PaymentGatewayId` (int, FK → PaymentGateways), `PaymentDate` (datetime), `Description` (nvarchar, Nullable), `CreatedBy` (nvarchar), `CreatedOn` (datetime), `UpdatedBy` (nvarchar, Nullable), `UpdatedOn` (datetime, Nullable), `IsDeleted` (bit), `DeletedBy` (nvarchar, Nullable), `DeletedOn` (datetime, Nullable) |
| `ExpenseCategories` | ? New | `Id` (int, PK), `Name` (nvarchar), `CreatedOn` (datetime) |
| `ExpenseTypes` | ? New | `Id` (int, PK), `ExpenseCategoryId` (int, FK → ExpenseCategories), `Name` (nvarchar), `SiteHolderId` (int, Nullable, FK → SiteHolders), `IsDeleted` (bit), `CreatedOn` (datetime) |
| `ExpenseAttachments` | ? New | `Id` (int, PK), `ExpenseId` (int, FK → SiteExpenses), `FileName` (nvarchar), `FileUrl` (nvarchar), `FileSize` (bigint), `FileType` (nvarchar), `UploadedOn` (datetime) |

### **1.1 Schema Diagram**

```mermaid
erDiagram
    ExpenseCategories {
        int Id PK
        string Name
        datetime CreatedOn
    }
    ExpenseTypes {
        int Id PK
        int ExpenseCategoryId FK
        string Name
        int SiteHolderId "Nullable FK"
        bit IsDeleted
        datetime CreatedOn
    }
    SiteExpenses {
        int Id PK
        int SiteId FK
        int ExpenseCategoryId FK
        int ExpenseTypeId FK
        string Name
        decimal Amount
        int PaymentGatewayId FK
        datetime PaymentDate
        string Description
        bit IsDeleted
        datetime CreatedOn
    }
    ExpenseAttachments {
        int Id PK
        int ExpenseId FK
        string FileName
        string FileUrl
        bigint FileSize
        string FileType
        datetime UploadedOn
    }

    ExpenseCategories ||--o{ ExpenseTypes : "categorizes"
    ExpenseCategories ||--o{ SiteExpenses : "classifies"
    ExpenseTypes ||--o{ SiteExpenses : "typed by"
    SiteExpenses ||--o{ ExpenseAttachments : "has attachments"

2. Modification of the Drug Index Table

• Objective: Add country-specific drug data support to the centralized drug index.
• Action: Add a CountryId column (type: Int, FK to Country table) to the DrugIndex table.
  • Map Excel columns to DB schema:
    • TradeName, NameAr ← Product column
    • GenericName ← Molecule column (strip "Combination Of" prefix)
    • Shape ← Pack column
    • ManufacturingCompany ← ParentCompany column
    • Manufacturer ← Manufacturer column
    • Pharmacology ← Therapeutic class column
  • Insert Iraq record into Country table
  • Set CountryId = Egypt ID for all existing records
  • Insert new Iraq drug records with CountryId = Iraq ID
  • Create background sync job: SyncIraqDrugIndexJob

3. Modification of Drug Index API Search

• Objective: Filter drug index search results by the doctor's country.
• Action: Extract CountryId from the authenticated doctor's JWT token and use it to filter results.
  • endpoints to be updated:
    • PUT: api/PortalDoctors/Login — return CountryId in response
    • GET: api/DrugIndexes/Search?key=&isHiv= — apply CountryId filter

---

## Notes

- This skill is designed for backend/API-heavy systems (ASP.NET, REST APIs, SQL Server)
- Can be adapted for frontend (Angular) changes by adding component/service names in Action bullets
- The **DB Changes Summary Table** + **Schema Diagram** pair should always open the document when DB changes are present — reviewers and DBAs need this upfront
- Mermaid ERDs render natively in GitHub, Azure DevOps Wiki, GitLab, and most modern markdown viewers
- When images/screenshots are referenced in requirements, add a placeholder note: `[Screenshot: description]`
- This skill pairs well with the **docx** skill if the output needs to be exported as a Word document