research-ts-decisions

name	research-ts-decisions
description	Research why the TypeScript team made a specific typing decision. Use when evaluating whether ts-reset should override a built-in type, or when triaging issues that propose type changes. Searches the microsoft/TypeScript repo for relevant issues, PRs, and team comments.
user-invocable	true

Research TypeScript Team Decisions

When evaluating whether ts-reset should override a TypeScript built-in type, research what the TypeScript team has said about it. Understanding their reasoning lets us make informed decisions — either agreeing with their trade-off or deliberately choosing a different one.

Who to look for

Ryan Cavanaugh (@RyanCavanaugh) is the TypeScript project lead and usually the one making final verdicts on typing decisions. His comments carry the most weight. Also look for comments from:

• Daniel Rosenwasser (@DanielRosenwasser) — TS program manager
• Anders Hejlsberg (@AHejlsberg) — original designer
• Nathan Shively-Sanders (@sandersn)

How to search

Step 1: Search GitHub issues directly

Use gh to search the microsoft/TypeScript repo. Try multiple queries — the issue might be about the specific method, the return type, or a broader pattern:

# Search issues by title/body
gh search issues --repo microsoft/TypeScript "Object.create return type" --limit 20

# Search with broader terms if the first query is too narrow
gh search issues --repo microsoft/TypeScript "Object.create" --limit 20

Step 2: Find team member comments

Once you have candidate issues, fetch comments and filter for TypeScript team members:

# Get Ryan's comments on a specific issue
gh api repos/microsoft/TypeScript/issues/{number}/comments \
  --jq '.[] | select(.user.login == "RyanCavanaugh") | {html_url, body}'

# Check for team comments more broadly
gh api repos/microsoft/TypeScript/issues/{number}/comments \
  --jq '.[] | select(.user.login == "RyanCavanaugh" or .user.login == "DanielRosenwasser" or .user.login == "sandersn" or .user.login == "ahejlsberg") | {user: .user.login, html_url, body}'

Step 3: Check for reverted PRs

Many typing decisions were tried, broke things, and got reverted. This history is critical:

# Search for PRs related to the topic
gh search prs --repo microsoft/TypeScript "Object.create" --limit 20

# Check if a PR was later reverted
gh api repos/microsoft/TypeScript/pulls/{number} --jq '{title, state, merged_at, body}'

Step 4: Search for related issues

TypeScript team members often state general principles on tangentially related issues. If the specific method doesn't have much discussion, search for related patterns:

# Example: if researching Object.create, also check Object.getPrototypeOf,
# or broader topics like "prototype typing" or "returns any"
gh search issues --repo microsoft/TypeScript "Object.getPrototypeOf any" --limit 10

Step 5: Web search as fallback

If GitHub search doesn't surface enough, use web search:

site:github.com/microsoft/TypeScript "Object.create" RyanCavanaugh

What to report

Structure your findings as:

1. Timeline — chronological list of relevant issues and PRs, with links
2. Key quotes — direct quotes from team members, with permalink URLs to the specific comments (not just the issue)
3. The reasoning — summarize why the current typing exists
4. Was it tried before? — note any attempts to change it that were reverted or rejected, and why
5. Relevance to ts-reset — does this fall in ts-reset's sweet spot, or is the current typing a deliberate trade-off?

Always include direct permalink URLs to specific comments, not just issue URLs. Use the html_url field from the GitHub API.

Common patterns in TS team reasoning

These recurring arguments come up frequently. Knowing them helps you search more effectively and contextualize what you find:

• "any can never be wrong, just less right" — Ryan's principle that any is a safe default that never produces false errors
• Breaking changes — the TS team is very cautious about changing return types that would break existing code
• "Soundness is not a goal" — TypeScript explicitly prioritizes practical usability over type-theoretic correctness
• Prototype vs own properties — methods dealing with prototypes are hard to type because TS's type system doesn't distinguish prototype properties from own properties
• PropertyDescriptorMap is untyped — any API that takes property descriptors can't carry type information through them