AI-Assisted Development Guide¶

This document provides guidance for working with AI coding assistants on the gaslamp project.

Quick Start¶

For new requests to the AI, use these patterns:

Markdown

# New feature
"Implement [feature] in [module]. Include TypeDoc documentation and tests."

# Bug fix
"Fix [issue] in [filename]. Current behavior: [X], Expected: [Y]"

# Refactoring
"Refactor [filename] for [clarity/performance/type safety]."

# Documentation
"Improve TypeDoc in [filename]. Focus on clarity for beginners."

For long content, use /tmp/ files: glab issue update <ID> --description "$(cat /tmp/file.md)"

Project Context¶

gaslamp: TypeScript library for Google Apps Script (GAS)

Goal: Simple, modular data operations (DataFrame, type checking, GAS integration)
Stack: TypeScript, Jest, Rollup, clasp
Key: Works in both Node.js (dev) and GAS (production)

Module Overview¶

Text Only

src/
├── torch/          # Core: Expression, BareFrame, FlameFrame, LazyFrame, AfterGlow
├── flamewright/    # Runtime type validation
├── gaslets/        # GAS wrappers (Book, Sheet, Calendar, Drive, Trigger)
├── gears/          # Utilities (ClockSmith, Counter, JunkPocket)
├── jestlite/       # GAS-compatible testing framework
└── remnantflicker/ # Warnings and deprecation

DataFrame Architecture¶

BareFrame: Minimal, schema-free (Map)
FlameFrame: Schema-validated using FlameWright
LazyFrame: Deferred evaluation for batch operations
API: Polars-style, method-chaining support

Code Standards¶

TypeDoc Documentation (Required)¶

Every public function/class must include:

TypeScript

/**
 * One-line summary describing purpose.
 *
 * @param name Parameter description
 * @returns Return value description
 *
 * @example
 * ```javascript
 * const result = gaslamp.myFunction(value);
 * ```
 *
 * @category SubArea
 */
function myFunction(name: string): string { }

Important: Use javascript language identifier in examples (not typescript) and include gaslamp. prefix for GAS compatibility.

For full documentation standards, see Docstring Standards.

Naming Rules¶

Type	Convention	Example
Variables/Functions	camelCase	`myFunction`, `userData`
Classes/Types	PascalCase	`MyClass`, `DataType`
Constants	UPPER_SNAKE_CASE	`MAX_SIZE`, `DEFAULT_VALUE`
Private members	`_prefix`	`_privateMethod()`

See Naming Guidelines for detailed conventions.

Commit Messages (Conventional Commits)¶

Text Only

type(scope): concise description

Optional body with context or rationale.

Types: feat fix docs style refactor perf test build chore

Breaking change: Add ! → feat!: breaking change description

See Naming Guidelines for full conventions.

Language Rules¶

Code: English only (variables, comments, docstrings, error messages)
Chat: English or Japanese (user preference)
NO: Japanese in code or docstrings

Development Workflow¶

Step 1: Understand Requirements¶

Text Only

Read issue #[number] first
Ask for clarification if unclear
Reference existing patterns in similar modules

Step 2: Implement Incrementally¶

Text Only

1. Small functional blocks (one method at a time)
2. Include TypeDoc immediately
3. Run tests after each change
4. Only commit when tests pass

Step 3: Quality Gates (Pre-Commit)¶

Bash

task build            # TypeScript compiles
task test             # All tests pass
task lint             # Lint passes
task format           # Format code
task docs:api         # Docs generate without errors

Or run all checks at once:

Bash

task validate         # Comprehensive local validation

Step 4: Commit & Document¶

Text Only

Use Conventional Commits format
Reference related issues
Include rationale in commit body

What to DO ✅¶

Be specific: "Implement [exact feature]" not "add something"
Reference existing code: "Follow the pattern in [module]"
Request incremental work: "One method at a time"
Verify assumptions: "Does this match [pattern]?"
Include issue context: "Reference issue #123"
Ask for explanations: "Why does [code] work?"
Test at each step: "Run tests after changes"

What NOT to DO ❌¶

Ask for entire features at once
Assume AI understands full codebase
Accept code without reading it
Skip documentation for public APIs
Ignore test failures or errors
Use Japanese in code/comments/docstrings
Make breaking changes without discussion
Invent new modules/functions without approval

GAS-Specific Constraints¶

These are forbidden in GAS:

Forbidden	Reason
Node.js modules (fs, path, os, etc.)	Not available in GAS
Global vars (process, global, __dirname)	GAS doesn't provide them
ES2021+ syntax	GAS may not support
CommonJS (require/module.exports)	Use TypeScript import/export

Important: Type validation must be runtime-based (no compile-time checking in GAS).

Common Prompting Patterns¶

Pattern: New Implementation¶

Text Only

Implement [feature] in [module].

Requirements:
- [requirement 1]
- [requirement 2]

Reference pattern: [existing similar code]
Include TypeDoc and tests.

Response: Step-by-step code with explanations, test suggestions.

Pattern: Bug Fix¶

Text Only

Fix [issue] in [filename].

Current: [what happens now]
Expected: [what should happen]

Keep public API unchanged.

Response: Root cause analysis, fix code, test verification.

Pattern: Refactoring¶

Text Only

Refactor [filename] for [goal].

Current approach: [brief description]
Target: [brief description]

Maintain backward compatibility.

Response: Stage-by-stage refactoring with tests at each step.

Pattern: Code Explanation¶

Text Only

Explain how [component] works.
Why does [code] do [X]?
What are the design tradeoffs for [pattern]?

Response: Detailed explanation with code examples.

Sample Workflows¶

Implementing a Feature¶

Text Only

1. Request:
   "Implement [feature] in src/torch/[module].
    Requirements: [...]. Include tests."

2. AI Response:
   - Current state analysis
   - Proposed implementation approach
   - Design decisions explained

3. Review & Iterate:
   - Read proposed code
   - Ask questions if unclear
   - Request changes if needed

4. Verification:
   npm run build    # ✅ Compiles
   npm test         # ✅ Tests pass

5. Commit:
   git commit with conventional message

Fixing a Bug¶

Text Only

1. Request:
   "Reference issue #[N]. Fix [bug] in [filename].
    Current: [behavior]. Expected: [behavior]."

2. AI Response:
   - Analyzes root cause
   - Proposes fix
   - Includes test case

3. Verify:
   npm test                    # ✅ Bug fixed
   npm run build              # ✅ No side effects

4. Commit:
   Reference issue in message

Improving Documentation¶

Text Only

1. Request:
   "Improve TypeDoc in [filename].
    Make it clearer for beginners.
    Add practical examples."

2. AI Response:
   - Updated docstrings
   - More detailed @example sections
   - Better @remarks

3. Verify:
   npm run docs:api           # ✅ Generates cleanly

4. Commit:
   docs: improve TypeDoc in [module]

Issue Management¶

See ISSUES.md for GitLab CLI reference.

Common commands:

Bash

glab issue list                            # List open issues
glab issue view <ID> --comments            # View with comments
glab issue note <ID> --message "text"      # Add comment
glab issue close <ID>                      # Close issue

When referencing issues:

In commit messages: Closes #123
In code discussions: Reference #123 for context

Performance & Memory¶

GAS has strict limits:

Execution Time: ~6 min per run (max)
Memory: Limited heap
API Calls: Quota-limited
Implications:
Batch operations when possible
Use LazyFrame for large datasets
Cache results appropriately

Summary¶

Key principles for AI collaboration:

Be Clear: Specific requests with context
Work Incrementally: Small, testable chunks
Verify: Run tests at each step
Document: Maintain TypeDoc and commit messages
Reference: Link to issues and existing patterns

Asking for Help¶

Good ways to engage:

"Can you explain how [component] works?"
"What's the design pattern for [situation]?"
"How would you implement [feature] following gaslamp patterns?"
"Why does [code] need [constraint]?"
"What tests would cover [scenario]?"

Key: The more specific and contextual, the better the AI's response.