PR Description Generator

Workflow

1. Identify the repository and branch - Determine which repository and branch the PR is for. If not specified, ask the user. The workspace may contain multiple repositories (e.g., incan/, IncQL/).
2. Locate the PR template - Find .github/pull_request_template.md in the repository root. If not found, use the standard template from the repository's .github/ folder.
3. Gather context - Run git diff main...HEAD (or the appropriate base branch) to see all changes. Also check git log main..HEAD --oneline for commit messages.
4. Check for associated issue - Extract issue number from branch name (e.g., bugfix/184-... → issue #184) or check commit messages for Fixes #NNN, Closes #NNN, etc.
5. RFC lifecycle preflight - If the branch implements an RFC or touches workspaces/docs-site/docs/RFCs/*, inspect the governing RFC before drafting the PR body.
   • If the RFC is In Progress and the branch implements the full RFC scope, use bump-rfc first so the RFC is Implemented, moved into closed/implemented/, and reflected in the PR diff before the PR is presented for review.
   • If the branch implements only part of the RFC, keep the RFC active and state the remaining scope clearly in the PR body.
   • Do not draft a review-ready PR description that claims full RFC completion while the RFC file still says In Progress.
6. Analyze the changes - Categorize the changes by:
   • Type (bug fix, new feature, refactor, docs, CI/tooling, RFC)
   • Area(s) affected (Incan Language, Compiler, Tooling, Editor, Runtime, Docs)
   • User-facing behavior changes
   • Internal architectural changes
   • Risks or breaking changes
7. Fill in the template - Use the analysis to populate each section of the PR template.
8. Add issue reference - If an issue number was found and the diff completes its verified scope, append Closes #<issue number> at the end of the PR description. Use Refs #<issue number> when the PR delivers only part of the issue.
9. Output the PR description - Return the complete PR description in markdown format, ready to be used in a pull request.

PR Template Location

The skill automatically locates the PR template at:

• .github/pull_request_template.md in the repository root

If the template is not found, the skill uses the standard template structure.

Template Sections

Summary

• What does this PR change, and why?
• One tight paragraph summarizing the change.

Type of change

• Bug fix, New feature, Refactor/maintenance, Documentation, CI/tooling, or RFC

Area(s)

• Incan Language (syntax/semantics)
• Compiler (frontend/backend/codegen)
• Tooling (CLI/formatter/test runner)
• Editor integration (LSP/VS Code extension)
• Runtime / Core crates (stdlib/core/derive)
• Documentation

Key details

• User-facing behavior: what changes for users?
• Internals: what changed architecturally?
• Risks: what could break?

Testing / verification

• make test / cargo test
• make examples (if relevant)
• incan fmt --check . (if relevant)
• Manual verification notes

Docs impact

• No docs changes needed
• Docs updated
• Docs follow Divio intent (tutorial/how-to/reference/explanation)

Output Format

Return the PR description in markdown format, ready to be used in a pull request. Include all sections of the template, with checkboxes for items that need user verification. If an issue number was found, close it only when the diff completes its verified scope; otherwise append Refs #<issue number>.

For RFC-driven PRs, include the final RFC lifecycle state in the verification or docs section. If full RFC scope is implemented, the PR description should reference the RFC under workspaces/docs-site/docs/RFCs/closed/implemented/; if it is not, describe the remaining RFC checklist items instead of using a closing keyword that would close the issue.

Examples

Example 1: Bug Fix in incan

User prompt: "Create a PR description for bugfix/184 in the incan repo"

Output:

## Summary

This PR fixes RFC 042 trait supertrait assignability and generic upcast compatibility checks in the typechecker, and improves project root resolution logic for multi-file Incan projects.

**Bug fixes:**
- Trait-typed values are now correctly assignable to supertrait return types (e.g., `def to_root(x: Mid) -> Root: return x` where `Mid with Root`)
- Generic trait upcasts work correctly with compatible type arguments (e.g., `BoundedDataSet[T]` → `DataSet[T]`)
- Transitive supertrait generics substitute properly through the hierarchy
- Concrete adopters satisfy transitive supertrait annotations

**Infrastructure improvements:**
- Enhanced project root resolution in `build.rs` and `common.rs` to handle cases where the manifest is not found, defaulting to inferred project root
- Added logic to resolve imports from the project source root when in non-source directories (for example, `loaves/compiler/incan_driver/tests/`)
- Improved source root detection with manifest-based configuration support

## Type of change

- [x] Bug fix
- [ ] New feature
- [ ] Refactor / maintenance
- [ ] Documentation
- [ ] CI / tooling
- [ ] RFC (adds/updates `docs/RFCs/*`)

## Area(s)

- [x] Incan Language (syntax/semantics)
- [x] Compiler (frontend/backend/codegen)
- [ ] Tooling (CLI/formatter/test runner)
- [ ] Editor integration (LSP/VS Code extension)
- [ ] Runtime / Core crates (stdlib/core/derive)
- [ ] Documentation

## Key details

- **User-facing behavior**: Trait-typed values can now be returned as supertrait types without explicit casting. Generic trait hierarchies with compatible type arguments are correctly recognized as assignable.
- **Internals**: Added transitive supertrait closure computation, updated type compatibility checks for trait-to-trait upcasts (including generic arguments), and improved module resolution to fallback to project source root for imports in non-source directories.
- **Risks**: The typechecker changes affect trait assignability checks; existing code that relied on incorrect rejection of valid upcasts may now compile. The module resolution changes improve import handling but could affect edge cases with unusual project structures.

## Testing / verification

- [x] `make test` / `cargo test`
- [x] `make examples` (if relevant)
- [x] `incan fmt --check .` (if relevant)
- [ ] Manual verification described below

**Tests added:**
- `test_trait_supertrait_assignability_codegen` - validates RFC 042 upcast codegen
- `test_supertrait_cycle_is_diagnosed` - validates cycle detection
- `test_supertrait_transitive_closure` - validates transitive supertrait resolution
- `test_types_compatible_trait_to_supertrait_named` - validates named trait upcasts
- `test_types_compatible_trait_to_supertrait_generic` - validates generic trait upcasts
- `test_types_compatible_trait_to_supertrait_transitive_generic` - validates transitive generic upcasts
- `test_check_with_imports_concrete_and_supertrait_upcasts` - validates cross-module upcasts

## Docs impact

- [x] No docs changes needed
- [ ] Docs updated
- [ ] Docs follow Divio intent (tutorial/how-to/reference/explanation) where applicable

The RFC 042 specification is the normative source for trait supertrait assignability semantics.

## Checklist

- [ ] I kept public docs user-focused and moved internals to contributing docs when appropriate
- [ ] I avoided duplicating canonical install/run instructions in multiple places
- [ ] I added/updated tests where it materially reduces regressions

Closes #184

Example 2: New Feature in incan (without issue)

User prompt: "Create a PR description for feature/180 in the incan repo"

Output:

## Summary

This PR implements RFC 035: First-class named function references in Incan. Named `def` functions can now be passed as values, stored in variables, and placed in collections without wrapping in a closure. `Callable[Params, R]` is accepted as syntactic sugar for `(Params) -> R` and desugared at parse time.

## Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Refactor / maintenance
- [ ] Documentation
- [ ] CI / tooling
- [ ] RFC (adds/updates `docs/RFCs/*`)

## Area(s)

- [x] Incan Language (syntax/semantics)
- [x] Compiler (frontend/backend/codegen)
- [ ] Tooling (CLI/formatter/test runner)
- [ ] Editor integration (LSP/VS Code extension)
- [ ] Runtime / Core crates (stdlib/core/derive)
- [ ] Documentation

## Key details

- **User-facing behavior**: Named functions can now be used as first-class values. The `Callable[Params, R]` syntax provides a convenient way to express function types.
- **Internals**: Parser now recognizes `Callable` as a type sugar and desugars it to the canonical function type. Typechecker validates function references and their signatures. Lowering emits Rust closures for function references.
- **Risks**: This is a new language feature; existing code is not affected. The `Callable` sugar may conflict with future type aliases named `Callable`.

## Testing / verification

- [ ] `make test` / `cargo test`
- [ ] `make examples` (if relevant)
- [ ] `incan fmt --check .` (if relevant)
- [ ] Manual verification described below

**Tests added:**
- Typechecker tests for function reference type checking
- Codegen snapshot tests for function reference emission
- Integration tests for function reference usage

## Docs impact

- [ ] No docs changes needed
- [x] Docs updated
- [ ] Docs follow Divio intent (tutorial/how-to/reference/explanation) where applicable

**Docs updated:**
- Language reference for function references
- Tutorial for first-class functions
- RFC 035 implementation notes

## Checklist

- [ ] I kept public docs user-focused and moved internals to contributing docs when appropriate
- [ ] I avoided duplicating canonical install/run instructions in multiple places
- [ ] I added/updated tests where it materially reduces regressions
Closes #2```

### Example 3: PR in IncQL repo

**User prompt:** "Create a PR description for feature/new-dataset-api in the IncQL repo"

**Output:**
```markdown
## Summary

This PR adds a new dataset API for IncQL that provides a unified interface for both bounded and unbounded data streams. The API is built around the `DataSet[T]` trait hierarchy with `BoundedDataSet[T]` and `UnboundedDataSet[T]` intermediate traits.

## Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Refactor / maintenance
- [ ] Documentation
- [ ] CI / tooling
- [ ] RFC (adds/updates `docs/RFCs/*`)

## Area(s)

- [x] Incan Language (syntax/semantics)
- [ ] Compiler (frontend/backend/codegen)
- [x] Tooling (CLI/formatter/test runner)
- [ ] Editor integration (LSP/VS Code extension)
- [ ] Runtime / Core crates (stdlib/core/derive)
- [ ] Documentation

## Key details

- **User-facing behavior**: Authors can now write pipelines that work with both batch and streaming data using the same API. The type system enforces streaming constraints at compile time.
- **Internals**: Added `DataSet[T]`, `BoundedDataSet[T]`, `UnboundedDataSet[T]` traits and `DataFrame[T]`, `LazyFrame[T]`, `DataStream[T]` concrete types to the IncQL library package.
- **Risks**: This is a new API; existing code is not affected. The trait hierarchy may need adjustment based on user feedback.

## Testing / verification

- [ ] `make test` / `cargo test`
- [ ] `make examples` (if relevant)
- [ ] `incan fmt --check .` (if relevant)
- [ ] Manual verification described below

**Tests added:**
- Trait hierarchy tests
- Type assignability tests
- Operation API tests

## Docs impact

- [ ] No docs changes needed
- [x] Docs updated
- [x] Docs follow Divio intent (tutorial/how-to/reference/explanation) where applicable

**Docs updated:**
- `docs/language/reference/dataset_types.md` - Reference documentation
- `docs/language/explanation/dataset_types.md` - Explanatory documentation
- `docs/rfcs/001_incql_dataset.md` - RFC 001

## Checklist

- [ ] I kept public docs user-focused and moved internals to contributing docs when appropriate
- [ ] I avoided duplicating canonical install/run instructions in multiple places
- [ ] I added/updated tests where it materially reduces regressions