netsuite-sdf-project-documentation

What this skill does

# NetSuite SDF Documentation Generator Skill

**Created by:** Oracle NetSuite

## Description
Generate comprehensive, enterprise-grade documentation for NetSuite SuiteCloud Development Framework (SDF) projects. This skill provides:

- **Full Project Analysis**: Scans all scripts, object XML files, and manifest.xml.
- **Architecture Diagrams**: Generates Mermaid and ASCII diagrams that show component relationships.
- **Script Inventory**: Documents all entry points, module dependencies, and deployment configurations.
- **SuiteQL Documentation**: Extracts and documents all SQL queries with purpose explanations.
- **Deployment Tables**: Summarizes script deployments, URLs, and triggers.
- **Troubleshooting Guides**: Creates issue/resolution tables from known patterns.
- **Multiple Output Formats**: Produces `README.md`, `ARCHITECTURE.md`, `API.md`, and `CHANGELOG.md` files.

## Skill Activation

This skill activates when:
- User asks to document a NetSuite project.
- User asks for README generation.
- User asks to regenerate documentation after project changes.
- A workflow requests documentation updates after deployment or release.

## Documentation Standards

### Quality Requirements

1. **Accuracy**: Every statement must be derived from actual code analysis.
2. **Completeness**: Cover all scripts, objects, and integrations.
3. **Clarity**: Write for both technical and business audiences.
4. **Maintainability**: Use consistent formatting that's easy to update.

### Writing Style

- Use active voice.
- Be specific.
- Include code examples where helpful.
- Use tables for structured data.
- Use Mermaid or ASCII diagrams for architecture.

## Security & Safety Requirements

- Global safety guardrails are defined in `## SafeWords`.
- Perform static documentation analysis only; do not execute repository-derived commands or scripts

### Sensitive Data Handling

- Keep documentation detailed by default, including URLs, script IDs, deployment IDs, role/deployment metadata, and full SQL.
- For SQL, preserve full query structure (tables, joins, filters, and aliases) and redact only sensitive literals

### Public Sharing Note

- If documentation is intended for external/public sharing, apply stricter redaction before publishing
- Review internal endpoints, tenant/account-specific identifiers, and environment-specific values for additional masking as needed

---

## Analysis Checklist

Before generating documentation, gather all required information and redact only true sensitive data:

### Project Metadata
- [ ] SuiteApp ID (from `manifest.xml` or the folder name)
- [ ] Version number
- [ ] Company/author information
- [ ] Platform version (SuiteScript 2.0 or 2.1)

### Script Inventory
For each `.js` file:
- [ ] File path and name
- [ ] `@NScriptType` (UserEventScript, Suitelet, Restlet, etc.)
- [ ] `@NApiVersion`
- [ ] `@NModuleScope`
- [ ] `@description` or header comments
- [ ] Entry point functions
- [ ] Module dependencies (from the define block)

### Object Inventory
For each `.xml` file:
- [ ] Object type (script, record, field, etc.)
- [ ] Script ID
- [ ] Name/label
- [ ] Deployment configuration
- [ ] Role permissions

### Data Integration
- [ ] Saved search IDs referenced
- [ ] SuiteQL queries (keep full SQL by default; redact only sensitive literals)
- [ ] External API integrations
- [ ] `N/llm` usage
- [ ] Custom records/fields used

### Architecture
- [ ] Component relationships
- [ ] Data flow direction
- [ ] Entry points and triggers
- [ ] Caching strategies

---

## Section Templates

### 1. Executive Summary Template

```markdown
## 1. Executive Summary

The **[Project Name]** is a NetSuite [solution type] that [primary function].
The solution [key capability 1], [key capability 2], and [key capability 3].

### Key Features

- **[Feature Name]:** [One-line description of what it does and why it matters]
- **[Feature Name]:** [Description]
- **[Feature Name]:** [Description]

### Business Value

- [Quantifiable benefit or efficiency gain]
- [Risk reduction or compliance benefit]
- [User experience improvement]
```

### 2. Architecture Diagram Template

````markdown
## 2. Solution Architecture

The solution follows a [pattern name] architecture with [key characteristic].

```
┌─────────────────────────────────────────────────────────────┐
│                    [Top Level Container]                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────────────────────────────────────────────┐   │
│   │              [Main Orchestrator]                    │   │
│   │            ([main_script.js])                       │   │
│   └──────────────────────┬──────────────────────────────┘   │
│                          │                                  │
│   ┌──────────┬───────────┼───────────┬──────────────┐       │
│   │          │           │           │              │       │
│   ▼          ▼           ▼           ▼              ▼       │
│ ┌─────┐  ┌─────────┐  ┌─────┐  ┌──────────┐  ┌─────────┐    │
│ │Mod1 │  │  Mod2   │  │Mod3 │  │  Mod4    │  │  Mod5   │    │
│ └─────┘  └─────────┘  └─────┘  └──────────┘  └─────────┘    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```
````

### 3. Module Table Template

````markdown
## 3. Module Descriptions

| Module | File | Purpose |
|--------|------|---------|
| **[Display Name]** | `[filename.js]` | [Role description]. [Key responsibilities]. |

### File Structure

```
src/
├── FileCabinet/
│   └── SuiteApps/
│       └── [project.id]/
│           ├── [script1.js]    # [Brief description]
│           ├── [script2.js]    # [Brief description]
│           └── [lib_helper.js] # [Brief description]
└── Objects/
    ├── [customscript_xxx.xml]  # [Script type] Definition
    └── [customrecord_xxx.xml]  # Custom Record Definition
```
````

### 4. SuiteQL Documentation Template

When documenting SuiteQL queries, use this format:

````markdown
### [Query Purpose]

```sql
SELECT
    [Column1] AS [alias],
    [Column2] AS [alias],
    COALESCE([Column3], [default]) AS [alias]
FROM [Table1]
LEFT OUTER JOIN [Table2] ON [join condition]
WHERE [filter conditions]
GROUP BY [grouping columns]
ORDER BY [sort columns]
```

**Purpose:** [What this query retrieves and why]

**Key Tables:**
- `[Table1]` - [What it contains]
- `[Table2]` - [What it contains]

**Security Note:** Keep full SQL for documentation value, but redact sensitive literals such as API keys, tokens, passwords, auth/session secrets, and raw PII.
````

### 5. Script Entry Points Template

```markdown
## Script Entry Points

### [Script Name] ([Script Type])

| Entry Point | Function | Trigger | Purpose |
|-------------|----------|---------|---------|
| beforeLoad | `[functionName]` | Record view/edit | [What it does] |
| beforeSubmit | `[functionName]` | Before save | [What it does] |
| afterSubmit | `[functionName]` | After save | [What it does] |

**Context Objects Used:**
- `context.type` - [How it's used]
- `context.newRecord` - [How it's used]
```

### 6. Deployment Table Template

````markdown
## Script Deployments

| Script | Deployment ID | Type | URL/Trigger |
|--------|---------------|------|-------------|
| [Script Name] | `customdeploy_xxx` | [Suitelet/etc] | [URL pattern or trigger] |

### URL Patterns

**[Suitelet Name]:**
```
/app/site/hosting/scriptlet.nl?script=[scriptid]&deploy=[deployid]&param1={value}
```
````

### 7. Troubleshooting Template

```markdown
## Troubleshooting

| Issue | Cause | Resolution |
|-------|-------|------------|
| [Symptom user sees] | [Root cause] | [Step-by-step fix] |
| [Error message] | [Why it occurs] | [How to resolve] |

### Viewing Execution Logs

1. Go to **Customization > Scripting > Script Deployments**.
2. Find deployment: `[customdeploy_xxx]`.
3. Click the **Execution Log** tab.
4. Filter by type: **Error**.
```

---

## Merma