r3xsean/see-it-through

사용자의 요청에서 코드 변경을 최종 목적지까지 이끌고, 다른 모델을 리뷰어로 활용합니다. 사용자는 두 번 결정합니다: 설명자(explainer)에서 접근 방식, 그리고 선적 메시지(ship message)에서 결과를 결정합니다. 그 사이의 모든 것은 당신의 몫입니다.

다른 모델은 사용자가 지정한 제품군(family)의 orchestrator_capabilities 중 최신 모델이며, 사용자가 지정한 노력 수준(effort)으로 작동합니다. 동일한 모델과 노력수준이 아래의 모든 백엔드포스(back-and-forth)와 코드 루프, 리뷰에 사용되며, 중요한 결정에 대한 토론은 예외입니다. 제품군이나 노력 수준이 누락된 경우, 이를 묻고 사용자가 응답할 때까지 다른 작업을 하지 않습니다.

러너(runner)는 3단계에서 접근 방식을 논쟁합니다 (백엔드포스 스킬의 러너). 사용자가 러너를 명시하지 않는 경우: 중간 노력 수준의 최신 Fable 모델이 다른 모델과 토론합니다. 중요한 결정의 경우, 높은 노력 수준의 최신 Fable 모델이 높은 노력 수준의 최신 Astra 모델과 다른 모델을 대신하여 토론합니다. 중요한 결정은 design.md의 구조적 질문에서 트리거가 발생하고 접근 방식을 변경할 수 있는 질문을 명시할 수 있는 경우입니다. 러너 또는 파트너의 모델을 사용할 수 없는 경우, 이를 알리고 다른 모델과 함께 직접 접근 방식을 논쟁합니다.

1. 목적지와 규칙

변경이 끝나는 위치를 파악합니다: 테스트된 로컬 변경, 푸시된 브랜치, 오픈된 PR, 머지됨, 또는 배포됨. 불명확하고 답변이 작업을 변경하는 경우에만 질문합니다. "see it through" 라고 말하는 것은 푸시, PR 또는 배포를 승인하지 않습니다. 선적 메시지의 승인이 이를 승인합니다.

변경 중인 저장소의 규칙과 사용자가 가리키는 프로세스 파일이 이 스킬과 다른 경우 해당 규칙이 우선합니다.

이미 구축된 변경. 사용자가 변경이 이미 완료되었다고 말하는 경우, 구축된 것이 접근 방식이며, 선적 메시지는 첫 번째 승인입니다. 설명자를 보내지 말고 백엔드포스를 실행하지 마십시오. 2단계와 3단계를 대체하여:

• 베이스 고정: 머지되지 않은 브랜치의 경우, 해당 브랜치가 머지되는 브랜치와의 머지 베이스(마지막 머지 이후). 머지된 경우, 변경 이전의 커밋. 불명확한 경우 질문합니다. 변경이 이미 머지된 경우, 목적지는 이번 실행의 후속 커밋이 가는 곳입니다. 불명확한 경우 질문합니다.
• 사용자의 말과 변경 자체가 말하는 것(커밋 메시지, PR 텍스트)에서 요청을 작성하고, 추론한 내용을 표시합니다.
• 베이스의 워크트리에서 실패하고 변경에서 통과하는 검사를 찾습니다. 변경에 이미 있는 테스트로 시작합니다(변경의 테스트와 하니스 헝크만 적용하여 베이스에서 실행). 그 중 어느 것도 입증하지 못하는 약속된 동작에 대해서만 하나를 작성합니다. 실패를 보여주지 않는 변경(예: 속도 향상 또는 리팩터링)의 경우 약속된 내용을 확인하는 검사를 작성합니다. 단계 설정은 2단계와 동일합니다. 수용 기준선은 4단계가 유지하는 것과 같이, 변경이 약속하는 각 동작을 입증하는 최소한의 검사로 유지하며, 변경 후에 작성된 것을 기록합니다. 변경의 다른 테스트는 simplify.md에 열려 있습니다.
• 구축된 접근 방식을 파일로 작성: 변경된 내용, design.md의 근거와 구조적 질문에 대한 답변, 그리고 3단계의 실패 검사.

그런 다음 재현이 통과하는 것을 보여주며 4단계를 계속하고, 해당 베이스와 해당 파일을 접근 방식으로 하여 코드 루프를 실행합니다. 선적 메시지는 설명자가 승인되지 않았다고 말하고, 구조적 대안과 사용자가 받는 것을 변경하는 발견 사항을 포함합니다.

2. 재현

버그의 경우, 수정 사항을 작성하기 전에 베이스에서 재현합니다: 실패하는 테스트, 그리고 사용자가 버그를 볼 수 있는 경우, capture.md에 따라 실행 중인 제품에서 이를 캡처합니다(검증 흐름이 아직 캡처할 수 없는 경우 수동으로). 기능의 경우, 사용자가 보거나 할 수 있어야 하는 것을 작성합니다. 버그를 재현할 수 없는 경우, 수정 사항을 구축하기 전에 사용자에게 알리고, 이에 대해 말하는 모든 것은 "코드 읽기에서 (시도하지 않음)"로 작성합니다. 아무것도 찾지 못하는 검사는 해당 사항이 있을 때 찾는 것을 확인한 경우에만 유효합니다.

재현하지 않은 실패 경로에 대한 가드를 구축하지 말고, 대신 설명자에서 후속 조치로 나열합니다.

저장소의 검증 스킬을 통해 재현하고 입증합니다: 저장소의 .agents/skills/verify/ 또는 저장소의 AGENTS.md에 명시된 위치. 없는 경우 또는 필요한 흐름을 다루지 않는 경우, 지금은 수동으로 재현하고 make-verifiable 스킬로 해당 커버리지를 구축하는 것을 접근 방식의 일부로 만듭니다.

그런 다음 티어를 설정합니다. 전체(Full): 변경된 동작이 지속성, 동시성, 권한 부여, 마이그레이션, 공개 계약, 파괴적 효과 또는 공유 상태 소유권에 도달하거나, 변경된 코드에 도달하는 방법이나 테스트가 얼마나 잘 커버하는지 아직 알 수 없는 경우 (파일 이름이 아닌 찾은 호출자와 상태 작성자로 판단). 경량(Light): 그 외의 경우. 경량 실행 중 이러한 조건 중 하나가 발견되면 전체로 전환됩니다.

3. 설계 및 설명자

design.md를 읽고 접근 방식을 선택하기 전에 요청된 작업을 수행합니다. 전체 실행에서는 접근 방식에 대해 모델과 백엔드포스를 수행합니다 (백엔드포스 스킬), design.md의 비율 추정치를 컨텍스트의 전제로 확인하고, 더 작은 버전과 변경 없음 옵션을 포함합니다. 경량 실행에서는 design.md의 트리거가 발생하거나 강력한 접근 방식이 실질적으로 다른 경우에만 수행하고, 그렇지 않으면 직접 접근 방식을 작성합니다. 러너에게 컨텍스트에서 참조 정보와 함께 근거, 재현한 내용과 읽기만 한 내용, 세션의 스크래치패드 또는 임시 폴더에 기록할 경로를 제공합니다. 질문(사용자가 요청에서 작성)에서는 변경이 적용되는 위치, 호출자 및 관련 사례, 수용 케이스, 그리고 사용자에게 남겨진 작업도 물어봅니다. 설계 질문이 실행하여 관찰할 수 있는 사실인 경우, 사용자에게 묻지 말고 격리된 체크아웃 또는 스크래치 데이터에서 일회성 실험으로 해결합니다. 실험은 아무것도 배송하지 않습니다.

그런 다음 실패 검사를 작성합니다: code-loop 스킬의 brief 헤더에 있는 조건과 변경하는 동작에 의존했던 대상을 검토하고, 각각에 대해 이를 커버할 테스트 이름을 지정하거나 수용하는 제한 사항을 명시합니다.

사용자에게 **설명자(explainer)**를 보냅니다. 다음 제목 아래에 평이한 언어로, 순서대로, 각 내용을 한 번씩 말합니다.

• 문제: 오늘날 사용자가 보는 것, 누가 얼마나 자주 겪는지 (관찰 또는 추정; 보고서가 없으면 알 수 없음, 드물지 않음), 왜 중요한지, 재현 결과 및 캡처(있는 경우); 기능의 경우 오늘날 누락된 것. 사용자가 변경을 요청한 경우, 사용자의 말로 시작합니다.
• 발생 원인: 평이한 용어로 원인; 기능의 경우 방해가 되는 것. 방해가 되는 것이 없으면 기능의 경우 이 제목을 생략합니다.
• 변경 사항: 완료되었을 때 사용자가 보거나 확인할 수 있는 것, 범위를 벗어난 것. 작업을 변경할 수 있는 것이 누락된 경우 여기서 요청합니다.
• 접근 방식: 코드에서 변경되는 내용과 위치, 입증 방법 (make-verifiable 작업 포함, 변경과 함께 제공되거나 증거로 남는 검사, 제공 및 유지 비용, 문제 하에서 도달 범위와 피해 대비 가치, 리뷰어가 관심 가질 실패 검사 항목).
• 검토된 대안: 모든 강력한 대안, design.md의 구조적 옵션 (신뢰할 수 있는 옵션이 있을 때마다), 각각이 선택되지 않은 이유.
• 리뷰어가 물을 수 있는 것: 각각의 예상 질문과 답변.

그런 다음 중단합니다: 사용자가 승인할 때까지 아무것도 구축하지 마십시오. 어떤 표현의 일반적인 승인으로 구축할 수 있습니다. 그 외의 모든 것은 말 그대로 동일한 백엔드포스에 추가 교환으로 들어가고(교환 한도 초과), 수정된 설명자로 돌아옵니다. 다시 중단합니다. 경량 실행에서 백엔드포스가 없는 경우, 직접 설명자를 수정하고 다시 중단합니다.

승인은 작성된 설명자를 다룹니다. 테스트, 데모 또는 리뷰가 사용자가 받는 것, 가시적 동작, 호환성, 범위, 배송을 위해 취할 조치, 또는 설명자가 수용한 트레이드오프를 변경하는 경우, 이를 위조하는 문장을 인용하고, 모델과 함께 해결하고, 변경된 사항을 명시하는 수정된 설명자를 보내고 다시 중단합니다. 내부 헬퍼 변경과 같은 작은 발견은 선적 메시지의 "변경 이후 변경된 사항"에 포함됩니다.

4. 구축 및 입증

동작을 변경하기 전에, 재현 및 변경이 존재하기 전에 실행할 수 있는 모든 수용 검사를 유지합니다: 설명자가 제공하는 것을 커밋하고, 나머지는 저장하거나(커밋할 것이 없을 때 모두) 저장소 외부의 패치로 저장합니다. 이들은 함께 수용 기준선이 되며, 최종 후보에서 다시 실행됩니다: 이후 편집은 코드 루프와 선적 메시지에 diff와 약속된 동작을 변경하는지 여부와 함께 전달됩니다.

승인된 접근 방식을 design.md가 설정한 순서대로 구축합니다. 변경이 검증 스킬이 다루는 흐름을 변경하는 경우, 동일한 변경에서 해당 흐름을 업데이트합니다. 2단계의 재현이 검증 스킬을 통해 통과하고, 사용자가 볼 수 있는 경우 실행 중인 제품에서 통과하는 것을 보여줍니다. 그런 다음 simplify.md에 따라 diff를 단순화합니다. 그런 다음 모델과 함께 전체 diff에 대한 코드 루프를 실행합니다 (code-loop 스킬), 사용자의 요청(또는 이를 대표하는 brief)을 Request로, 설명자를 Approach로(러너의 기록이 있으면 함께), 수용 기준선을 Acceptance로, 티어를 제공합니다.

최종 후보에서, 사용자가 변경된 것을 보거나 할 수 있는 경우, 검증 흐름을 통해 캡처하고, make-verifiable로 확장하여 흐름을 확장하고, 버그의 경우 동일한 시나리오를 베이스에서 동일한 흐름을 통해 캡처하여 before와 after가 일치하도록 합니다. capture.md에 따라 캡처를 선택, 생성 및 검토하고, 표시할 내용을 보여주는지 확인합니다. 캡처는 변경을 보여주고 검사가 이를 입증하므로, 베이스 또는 실패한 실행의 캡처는 결코 통과를 나타내지 않습니다. 볼 것이 없는 변경은 캡처가 없습니다.

5. 정리

프로젝트의 템플릿에서 PR, 이슈 또는 릴리스 텍스트를 작성합니다. 템플릿에 공간이 있거나 자체 제목 아래에 캡처를 포함합니다. GitHub에서 gh pr create --attach(또는 gh pr edit)로 게시할 때 캡처를 첨부합니다(저장소에 자체 도구가 없는 경우). 종료 코드가 0이 아닌 경우, 다시 시도하기 전에 PR이 이미 존재할 수 있으므로 PR을 확인합니다. 사실을 명시하는 공개 텍스트(설명, 답변, 상태 업데이트)가 나가기 전에, 모델의 새로운 리뷰어가 증거, 캡처(프레임 및 페이싱 보고서가 포함된 녹화) 및 diff와 대조하여 확인합니다: 모든 주장은 사실이고 뒷받침되며, 모든 체크 표시는 사실입니다. 증거가 뒷받침하지 않는 주장은 삭제합니다. 회피하지 마십시오.

푸시하기 전에, 이후 변경이 영향을 미칠 수 있는 각 체크 표시와 각 주장 뒤의 검사를 다시 실행하고 각 캡처를 다시 수행합니다.

6. 선적 메시지

사용자에게 보냅니다: 설명자를 2~3문장으로 요약, 변경 이후 변경된 사항, 증거, 캡처, 정리, diff, 승인 시 취할 정확한 조치. 코드 루프가 해결되지 않은 분쟁으로 끝난 경우, 이를 앞세웁니다: 각 주장, 각 측이 보여준 것, 승인 시 제공되는 것. 보내기 전에 design.md의 중복 검사를 다시 수행합니다. 사용자가 승인할 때까지 중단합니다.

7. 목적지까지

승인된 조치를 취한 다음 변경을 목적지까지 전달합니다:

• 각 푸시 전과 알림에 응답하기 전에 원격 헤드를 가져오고 변경의 현재 상태를 확인합니다. 다른 사람의 푸시 위에 구축하고, 커밋 해시가 아닌 트리를 비교합니다. 오래된 로컬 버전으로 그들의 작업을 대체하지 마십시오. 변경이 다른 사람의 버전에 의해 도착, 종료 또는 대체되는 경우, 목적지에 도달한 것과 마지막으로 확인한 헤드 및 공개된 발견 사항을 비교합니다. 다른 점이나 도달하지 못한 것을 보고하고, 의도적으로 제거한 것을 다시 추가하지 마십시오.
• 모든 리뷰 발견 사항(인라인 또는 리뷰 본문)은 전체를 읽고, 수정 사항 또는 한 줄 이유를 제공합니다. 베이스에서도 발생하는 발견 사항은 code-loop가 기존 발견 사항을 판단하는 방식으로 판단합니다. 동작을 변경하는 수정 사항은 코드 루프를 받습니다.
• 사실이 게시된 텍스트가 잘못되었음을 입증하는 경우, 텍스트를 수정합니다.
• 범위나 접근 방식을 변경하는 요청은 3단계로 돌아가고, 구축되면 새 선적 메시지로 이동합니다. 이 변경을 넘어 적용되는 요청은 도착 시 사용자에게 링크와 함께 전달됩니다. 여기서 수행해도 다른 곳에서는 수행되지 않습니다.
• 배포의 경우, 배포된 것에 대해 검증 흐름을 실행합니다.

8. 교훈

사용자, PR 리뷰어 또는 배송 후 어떤 것이 코드 루프가 놓친 문제를 발견했거나, 코드 루프가 차단기를 찾았거나 찾아야 했던 경우, 변경한 저장소의 .agents/lessons/log.md에 항목을 추가합니다. 사용자가 소유하지 않은 저장소의 경우, 사용자의 프로세스가 있는 폴더에 추가합니다. 각 항목: 날짜, 변경 사항, 무엇이 누구에 의해 발견되었는지, 모듈, 버그 클래스, 원인.

그런 다음 로그를 읽습니다. 검사가 잡을 수 있는 교훈이 두 번 보이면, lint, 타입, 테스트 또는 검증 검사가 됩니다. 판단이 필요한 교훈이 두 번 보이면, 저장소의 AGENTS.md에 한 줄이 됩니다. 한 모듈에 두 개의 항목, 또는 모든 모듈에서 하나의 버그 클래스에 두 개의 항목(예: 대기 중 다른 작업이 변경하는 상태)은 구조적 질문이 되며, 리팩터링이 제안되기 전에 공유 원인을 명명합니다. 각각을 최종 메시지의 후속 조치로 나열합니다. 리팩터링은 자체 see-it-through로 실행됩니다.

변경이 목적지에 도달했을 때, 또는 정확한 차단기와 남은 작업을 보고하고 교훈 항목(해당하는 경우)이 작성되었을 때 완료됩니다.