Sofa Contributor

SOFA Contributor

Назначение

Превращает находки из цикла разработки в качественные публикации на Stack Overflow for Agents и ведёт наблюдаемый реестр опубликованного. Это проектная обвязка поверх общего скилла sofa: sofa знает механику площадки (аутентификация, сессии, endpoints, голоса, верификации), а sofa-contributor знает наш процесс — что отбирать, как писать под стандарты площадки, куда складывать, как мерить отдачу.

Скилл фиксирует то, чему мы научились на реальных публикациях. Новые наблюдения («что залетает, что нет») дописывай прямо сюда — в рубрику отбора и чеклист качества, без промежуточного слоя вроде learnings.md.

Зависимость от скилла sofa

sofa-contributor не дублирует API-механику. Перед любой работой с площадкой загрузи скилл sofa (.claude/skills/sofa/) — он источник правды по аутентификации, сессиям, форматам запросов и обработке ошибок. Здесь — только проектные надстройки.

Креды агента лежат в ~/.sofa/credentials.json (агент Bbar0n234, base_url https://agents.stackoverflow.com). Ключ читай из файла, не печатай в вывод.

Три режима (progressive disclosure)

Скилл работает в одном из трёх режимов; в каждый заход подгружается ровно один reference-документ под задачу, не несколько:

• Плановая работа (отбор кандидатов в посты + write-back → черновики → публикация/отправка →

запись в реестр) — planned-work.md. Это режим роли sofa-contributor в оркестраторе и ручных публикаций.

• Blueprint-свип (периодический поиск вызревших категориальных паттернов по репозиторию под

публикацию Blueprint) — blueprint-sweep.md. Вызывается словами архитектора («сделай blueprint sweep»), вне итерации; локально и из облака одинаково, не FSM-роль и не cloud-routine. Публикация найденных кандидатов идёт штатными author-шагами planned-work.md.

• Опрос статистики (периодический сбор метрик опубликованных постов в реестр) —

stats-polling.md. Пока запускается вручную; к расписанию придём, когда формат устаканится.

Режимные доки — процедуры (последовательность шагов, их уникальная ценность). Нормативные правила — рубрика отбора, чеклист качества, грабли, author gate, структура реестра — живут здесь, в SKILL.md. Режимные доки на них ссылаются, а не пересказывают (иначе два источника правды разъезжаются). Единственный дом проектного ноу-хау по SOFA — этот файл.

Реестр публикаций

Каноничный реестр опубликованного — doc/content/sofa/:

• index.md — таблица всех постов (заголовок, тип, post_id, URL, итерация-родитель, статус,

последний снимок метрик, даты). Единый источник правды по тому, что опубликовано.

• posts/.md — на каждый пост: каноничное опубликованное тело + метаданные + дозаписываемый

лог статистики.

Provenance делим: генерация кандидатов живёт в папке итерации (sofa-proposals.md) — это WIP. После публикации каноничная запись переезжает в реестр. Так сохраняется «какая итерация родила пост» и централизуется живой трекинг.

Рубрика отбора кандидатов

SOFA-пост оправдан, когда инсайт сэкономит будущим агентам время или предотвратит повторную ошибку. Три типа верхнего уровня:

• TIL — проблема решена, инсайт привязан к конкретному фиксу/открытию. Наш основной формат.
• Blueprint — переиспользуемое знание уровня категории/паттерна, не частный случай.

Высокая планка; критерий и два источника производства — § Blueprint ниже.

• Question — открытая проблема (open problem): пробовали, решение с ходу не подобрали, как решать

пока не знаем. Отбор — по классификатору open-problem (§ Question ниже), источник — те же ## Follow-ups, что читает harvester.

Бери, когда совпадает хотя бы одно: удивительное поведение tool/API, нетривиальная интеракция систем, проваленные первые попытки с понятным «почему», долговечный фикс, проверенный локально.

Режь (по опыту feat-007):

• Общеизвестное, что дешевле найти в доках, чем читать пост (даже если у нас это «повторяемая

ловушка» — тогда нужен наш эмпирический угол + verbatim-ошибка, иначе мимо).

• Проектно-специфичное: доменные модели, наши классы/слои, бизнес-инварианты — непереносимо.
• Корректная штатная семантика инструмента, поданная как «открытие» — это не инсайт.
• Узкие находки лучше поглощать абзацем-caveat внутри смежного поста, чем плодить отдельный.

Question — классификатор open-problem

Источник кандидатов в Question — та же секция ## Follow-ups в tracks/*/summary.md, что читает harvester; отдельного стока нет (один источник истины). Но не каждый follow-up тянет на Question — классифицируй по природе долга:

• Open problem → кандидат в Question и одновременно штатно едет в backlog через harvester.

Признак: проблему пробовали решить, решение с ходу не подобрали, как решать — пока не знаем. Такой долг ценен как вопрос: чужой агент мог наступить на то же и знать ответ. Одно другого не отменяет — в backlog он едет, чтобы мы это пофиксили; в Question — чтобы спросить.

• Понятый-но-отложенный долг → только backlog, НЕ Question. Признак: причину разобрали,

откладываем лишь из-за времени/приоритета. В понимании уже «закрыто» — вопрос смысла не имеет.

Требования к Question-кандидату: соответствие формату question площадки (скилл sofa, GET /guidelines/question); контекст «что пробовали и почему не сработало» — из ## Решения и обоснования и ## Follow-ups трека; обобщён по чеклисту качества (без проектных специфик). Кандидаты идут в sofa-proposals.md под апрув архитектора — как посты и write-back (см. Author gate). После публикации Question backlog-пункт-источник дополняется обратной ссылкой на пост (провенанс, не перенос — пункт остаётся в backlog); мониторинг ответов — вручную через режим stats-polling (шаг 5 planned-work.md).

Blueprint — критерий и два источника

Blueprint оправдан только для категориального паттерна: проработанный с нуля сервис/слой, сильный design-brief, подход переносим на класс задач. Частный фикс — не Blueprint, его дом TIL. Планка высокая: сомневаешься «категория или случай» — это TIL или абзац-caveat в смежном посте, не Blueprint.

Два источника производства:

• (a) По горячим следам — на финализации итерации (sofa-contributor, planned-work.md). Оцени,

родила ли итерация паттерн уровня категории; источники — design-brief.md и ## Решения и обоснования треков. Кандидат — в sofa-proposals.md.

• (b) Периодический свип по репозиторию — режим blueprint-sweep.md, вызывается словами

архитектора («сделай blueprint sweep»), вне итерации. Паттерн часто не виден в одной задаче — наслаивается за дни/недели; свип читает design-brief'ы прошлых итераций и архитектурную доку doc/tech/, дедуплицирует против реестра и площадки. Процедура — в blueprint-sweep.md.

Чеклист качества (перед публикацией)

• Ищи дубли первым делом. GET /api/posts?search=... с нескольких углов + по тегам. Если

близкий пост есть — не плоди новый: верификация или реплай.

• Обобщай. Вычисти имя проекта, внутренние URL, имена наших классов/сервисов. Технические

специфики (версии, тексты ошибок, конфиги) оставляй, идентифицирующий контекст убирай.

• Не давай внешних ссылок. Code of Conduct площадки запрещает любые внешние URL в контенте.

Link guardrail рубит навигируемые схемы (http(s)://, ftp(s)://, ws(s)://) в любом месте тела, включая код-блоки — даже http://localhost:5173 в примере (422, url_allowlist: host not on allowlist). Источник называть текстом, origin/хосты — bare без схемы или плейсхолдером (``).

• Не шаблонь. Площадка прямо помечает одинаковую структуру секций (TL;DR/Environment/Root

cause/Fix из поста в пост) и засилье буллетов как AI-тэл, бьющий по репутации. Держи форму по содержанию, посты — разной формы. Не используй заголовки из guidelines как свои заголовки.

• Давай код и шаги. Для читателя-агента минимальный repro и точный фикс снимают неоднозначность.

Нумеруй реальную последовательность (repro, отладка, причинная цепочка); антипаттерн — рефлекторно бьющиеся на буллеты объяснения. Сниппеты держи минимальными и обобщёнными скелетами, не копипасть прод-код.

• Снимай verbatim-ошибки. Точный текст ошибки — то, что ищут поиском. Снять можно дёшево

(минимальный malformed-запрос на тот же endpoint), не гоняя весь сценарий. Не выдумывай строку, которой нет.

• Читай GET /guidelines/{til|blueprint|question} перед постингом — стандарты качества

площадки. GET /guidelines/code-of-conduct — политика (промо, манипуляция, ссылки).

• Сводка сути для автора (RU). Тело поста — на английском под площадку, но архитектор ревьюит

суть быстрее по-русски. Поэтому каждый финал-черновик начинается блоком ## Суть (для автора, RU): проблема → почему наивный путь не годится → решение → тип/теги, информативно и сжато. Это для ревью-гейта, в опубликованное тело не идёт (в реестр переезжает только английское тело).

Грабли публикации (проверено на практике)

• Нет эндпоинта правки поста. API даёт create/delete, не update. «Улучшить» опубликованный

пост = DELETE + создать заново (новый id). Удаление одностороннее.

• Порядок при рерайте: сначала delete, потом create. Дедуп-скрин рубит near-identical к твоим

же живым постам (422 duplication). Поэтому старую версию удалить до публикации новой. Тексты держать локально — потери знания нет, знание не зависит от живого поста.

• Сессия истекает — при 401 invalid_session пересоздать (см. скилл sofa).
• Sandbox изолирует сеть. Сетевые вызовы к площадке — вне sandbox (escape hatch для curl).

Write-back — замыкание петли потребления

SOFA у нас двунаправлен: consume-роли не только читают площадку, но и оставляют след, который финализация превращает в write-back — verify/vote/reply по постам, к которым обращались в ходе итерации. Это включает рычаг репутации, который простой постинг не трогает: репутацию растит верификатор по факту применения, а не только автор поста.

Откуда берутся кандидаты (context bus). Два носителя, оба заполняют consume-роли, оба читает sofa-contributor на финализации:

• ## SOFA-посты (id / применил / результат) в tracks//summary.md — TIL, тронутые fixer'ом

в цикле фикса (TIL-зонд 2-го захода).

• ## SOFA consulted в design-brief.md — Blueprint, к которым обращались при проработке дизайна

(правило conventions.md § Blueprint-ресёрч).

Секция пустая или её никто не заполнил → петля разорвана, кандидатов write-back нет (валидный исход).

Три формы (механика — в скилле sofa, здесь только когда что применять):

• verify — когда guidance поста применили и наблюдали исход. Обязателен outcome

(worked_as_written / worked_with_changes / did_not_work) + feedback ≤500 символов. Feedback — конкретика применения (что применил, что наблюдал, какая адаптация понадобилась), не общая оценка поста. Операционный мусор (хеши коммитов, env-строки, логи тестов) в feedback запрещён — гейты качества площадки его рубят, и другим читателям он бесполезен.

• vote — read-time-прогноз «стоит ли доверять», только по постам, которые фактически читались

(был GET детали поста; иначе площадка отклонит голос). Один голос на пост.

• reply — когда будущим агентам нужна видимая inline-оговорка: правка, caveat, коррекция,

альтернатива. Если суть — исход применения, это verify, а не reply.

Выбор минимальной формы, несущей сигнал, и разграничение verify↔reply — по скиллу sofa («Use the smallest action that captures the signal»). Write-back-кандидаты складываются в sofa-proposals.md рядом с пост-кандидатами; отправка — под апрувом (см. Author gate).

Author gate — публикация и write-back всегда под апрувом

Автономный конвейер (роль в оркестраторе) только генерирует кандидатов в sofa-proposals.md и останавливается — и для новых постов, и для write-back (verify/vote/reply). Сама публикация и отправка write-back — внешнее outward-facing действие под явным апрувом архитектора, никогда не автоматом. Это и by design площадки (human-in-the-loop), и наша политика. Ревью архитектора из процесса не уходит.

Ссылки

• .claude/skills/sofa/ — механика площадки SOFA (предусловие).
• doc/tech/sofa-pipeline.md — архитектура двунаправленной петли (обзорный документ).
• doc/content/sofa/ — реестр опубликованного.
• doc/workflow.md — место этапа в жизненном цикле итерации, роль sofa-contributor.
• planned-work.md, blueprint-sweep.md, stats-polling.md — режимы (этот каталог).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Bbar0n234
• Source: Bbar0n234/learnflow-ai
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.