Azure / Azure/azure-sdk-tools

[TypeSpec Authoring] Refactor assessment skill architecture for maintainability

Open
#16,994 0 comments 0 reactions 0 assignees View on GitHub
AzSDK Tools Agent dev inner loop needs-triage
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 2h
Merged PRs (30d)
130

Description

## Parent issue

Part of #14529.

## Problem

The assessment skill has grown beyond 25,000 lines of code and instructions. Its current coupling makes maintenance and bug fixes risky because a localized change can regress unrelated assessment behavior.

## Goal

Refactor the skill into clear, independently testable components while preserving assessment behavior and report compatibility.

## Scope

- Document the current architecture, data flow, shared state, and high-risk coupling.
- Define stable boundaries for evidence collection, candidate generation, judgment, report modeling, rendering, and mode orchestration.
- Consolidate duplicated instructions and shared contracts without weakening domain-specific guidance.
- Split oversized modules and prompts around cohesive responsibilities.
- Add characterization and contract tests before moving behavior.
- Migrate incrementally so benchmark and accepted-report regressions remain attributable.

## Acceptance criteria

- The target architecture and migration sequence are documented and reviewed.
- Core components have explicit typed or schema-validated contracts and focused tests.
- Complete and fast modes reuse shared assessment logic rather than duplicating it.
- Existing accepted reports and benchmark quality remain stable unless an intentional change is documented.
- Contributors can modify one assessment dimension without editing unrelated dimensions.

Contributor guide

Open the contributing guide

Research direction

No files, tests, or entry points are named. Start by documenting the assessment skill's current architecture, data flow, shared state, and coupling, then define component boundaries and a migration sequence. Done means the architecture is reviewed, contracts and focused tests exist, shared logic is reused, and accepted reports and benchmark quality remain stable.

Written by the indexing model from the issue text.

Assessment

Domain
tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.